…ples#247 UX.6 stress-caught)

Live stress test surfaced a cosmetic bug: when a cascade's changed
predecessor was the INTEGRATION node, the panel reason read clumsily —
'updating to include Integration — combine sub-issue results's change'
(the raw synthetic title in a possessive). Other rows already relabel
the integration node friendly, but the cascade REASON string did not.

- New exported cascadeNodeLabel(subIssueId, identifier, title): the
 synthetic integration node → 'the integration' (reads 'the
 integration's change'); real nodes prefer the Linear identifier.
- Reconciler's changedLabel now uses it.
- 4 unit tests pin the integration-possessive + identifier/title/fallback.

Full CDK suite green.

…h+settle the panel (aws-samples#247 UX.15 stress-caught)

Live stress test left the discount epic stuck at '🔄 4/5' forever: a
re-stack of ABCA-296 COMPLETED but the panel never cleared its
'🔄 updating' row and the epic never re-settled to ✅.

Root cause: a re-stack/iteration completing carries cascadeSubIssueId, so
the handler routes it to cascadeRestack — NOT reconcileTerminalChild
(which owns the panel refresh + all-terminal completion settle). When the
node has no dependents (planDirectRestack=0), cascadeRestack returned
EARLY, so the source node's updating row never cleared and completion
never re-ran. The old comment claiming restack completions 're-fire
reconcileTerminalChild' was simply false.

- Extracted refreshPanelAndSettle(orchestrationId, children, meta, now),
 shared by reconcileTerminalChild and cascadeRestack.
- cascadeRestack's no-dependents early-return now re-loads the snapshot
 and calls it, so the node's updating row clears and the epic settles
 to ✅ (or ⚠️) + mirrors parent state. cascadeRestack got a local now.
- UX.15 regression test: a re-stack of a no-dependents leaf where all
 children are terminal → panel refreshed ('complete', no stale
 'updating') + parent state mirrored.

Also includes the cascade-label fix (#47, aae0e66 already committed).
Full CDK suite green.

…#288) (aws-samples#302)

* docs(guides): note supported Node version range in Quick Start prerequisites

* feat(types): add 'jira' to ChannelSource union

Phase 1 of Jira Cloud integration (aws-samples#288). Extends the ChannelSource
discriminant on both sides of the wire and updates the agent-side
comment so the runtime knows 'jira' is a recognized channel value;
no behavior changes yet.

* feat(jira): add DDB table constructs for projects, users, workspaces

Phase 2 of Jira Cloud integration (aws-samples#288). Mirrors the Linear constructs
file-for-file. Composite PKs use cloudId as the tenant prefix
(`{cloudId}#{projectKey}`, `{cloudId}#{accountId}`) so the same project
key or account id stays unambiguous across distinct Atlassian tenants.
Tables are unwired until Phase 4 — JiraIntegration instantiates and
grants them.

* feat(jira): add webhook, processor, link Lambdas + shared helpers

Phase 3 of Jira Cloud integration (aws-samples#288). Mirrors Linear's adapter
shape: per-tenant OAuth resolver (auth.atlassian.com), X-Hub-Signature
HMAC verify with per-tenant + stack-wide fallback, REST-based feedback
poster (ADF-wrapped, no reaction primitive — marker folded into text),
and three Lambdas (webhook, processor, link).

Non-trivial bit: the processor diffs `changelog.items[]` where
`field === 'labels'` and tokenizes the space-separated `fromString` /
`toString` to detect a label add — Atlassian's diff format differs
from Linear's `updatedFrom.labelIds`. Includes a minimal ADF→markdown
walker for issue descriptions.

Handlers reference JIRA_* env vars set by the JiraIntegration construct
in Phase 4; they don't deploy yet.

* feat(jira): add JiraIntegration construct + stack wiring

Phase 4 of Jira Cloud integration (aws-samples#288). Mirrors LinearIntegration:
3 DDB tables, dedup table (8h TTL), 3 Lambdas (webhook/processor/link),
API routes under /jira/*, per-tenant `bgagent-jira-oauth-*` IAM grants,
cdk-nag suppressions.

Stack wiring grants the agent runtime GetSecretValue on the per-tenant
prefix and pipes the workspace registry table + Get/Put grant into the
orchestrator (matches Linear's path for pre-container failure feedback).
Synth confirms clean CloudFormation + no nag findings.

* feat(jira): wire agent-side MCP + OAuth resolver for jira channel

Phase 5 of Jira Cloud integration (aws-samples#288). Refactors channel_mcp.py from
a single-channel gate to a CHANNEL_MCP_BUILDERS dispatch dict so adding
future channels stays one-entry. Adds resolve_jira_oauth_token() to
config.py mirroring the Linear resolver — same race-handling, same
fail-closed semantics; only differences are the endpoint
(auth.atlassian.com, JSON body) and the env-var name (JIRA_API_TOKEN).

Pipeline now dispatches to the right resolver based on channel_source.
JIRA_MCP_URL is flagged in-source as needs-verification — Atlassian's
Remote MCP may still be preview-gated; if so, fall back to a REST shim
in a future jira_reactions.py module (Plan B).

Tests: 6 new Jira test cases in test_channel_mcp.py; full agent suite
remains green (825 passed).

* feat(cli): add bgagent jira commands (app-template, setup, link, map)

Phase 6 of Jira Cloud integration (aws-samples#288). Minimal v1 surface (4 of 10
Linear subcommands), per scoping decision. Mirrors the Linear CLI shape
where the contracts are similar:

- jira-oauth.ts ports linear-oauth.ts. Atlassian's token endpoint takes
  JSON (Linear takes form-encoded). offline_access scope is required
  for a refresh_token. fetchAccessibleResources() resolves cloudId +
  siteUrl post-consent.
- commands/jira.ts: app-template prints dev-console values; setup
  drives the OAuth dance + writes the per-tenant secret + registry row
  + webhook signing secret; link does dry-run preview UX; map writes
  the project → repo row.

Deferred to follow-ups: add-workspace, update-webhook-secret,
invite-user (with self-link picker), list-projects.

* test(jira): add webhook, processor, and link handler tests

Covers signature verify pass/fail, dedup, event filtering, label-add
detection (create vs update changelog), and Cognito-authenticated linking.
56 tests, mirrors the Linear handler test surface.

* docs(jira): add setup guide, ADR-014, and integration listings

- docs/guides/JIRA_SETUP_GUIDE.md — OAuth 3LO app, scopes, webhook
  registration, label trigger, project mapping, troubleshooting
- docs/decisions/ADR-014-jira-integration.md — Jira Cloud only, OAuth 3LO,
  label trigger, MCP outbound; documents the Jira-vs-Linear divergences
- README, USER_GUIDE, ROADMAP — add Jira to channel listings
- sync-starlight.mjs + astro.config.mjs — register the Jira guide mirror;
  regenerate Starlight content under docs/src/content/docs/

Completes the docs phase of aws-samples#288.

* test(jira): close build/coverage gaps for jira integration

Bring `mise run build` green on the jira integration branch:

- check-types-sync: allowlist JiraLinkResponse as CLI-only, matching
  SlackLinkResponse/LinearLinkResponse (link responses are inlined
  server-side; no CDK source-of-truth type)
- channel_mcp.py: move Callable into a TYPE_CHECKING block (ruff TC003;
  safe under `from __future__ import annotations`)
- agent.test.ts: bump expected DynamoDB table count 13 -> 17 for the
  four new Jira tables (project/user/workspace-registry/webhook-dedup)
- test_config.py: cover resolve_jira_oauth_token (cache, fallback,
  refresh, concurrent-refresh, malformed/expiry paths); agent coverage
  70.41% -> 72.91%
- jira-oauth-resolver.test.ts: new suite (32 tests) mirroring the Linear
  resolver tests; clears the CDK statement/line/function/branch gates
- jira.ts / jira-oauth.ts: ESLint --fix cosmetic edits (quote-props,
  redundant template literals)

Tests: 294 CLI + 837 agent + 1896 CDK, all passing.

* fix(jira): resolve cloudId from sole tenant when webhook omits it

Jira webhooks created via the Settings → System → Webhooks UI do not
include a top-level `cloudId` in their payload (only app/OAuth-registered
dynamic webhooks do). Without it the processor can't resolve the tenant,
so it dropped the event and never created a task — the inbound trigger
silently failed for the common single-tenant, UI-webhook setup.

Add a safe fallback: when `payload.cloudId` is absent, scan the workspace
registry and use the sole `active` tenant. Deliberately refuses to guess
when zero or multiple active tenants exist (returns undefined → event
dropped), so the multi-tenant design is preserved — a multi-tenant
operator must use a webhook that carries its own cloudId.

`grantReadData` on the registry table already covers the Scan, so no IAM
change is needed.

Adds tests for: sole-tenant recovery (task created), empty registry
(drop), and multiple active tenants (ambiguous → drop).

* feat(jira): post issue progress comments via REST shim

Jira-origin tasks now comment on the originating issue at start
("🤖 picked up…") and on completion ("✅ finished — PR: <url>" / "❌ …"),
matching the Linear integration's progress UX.

Why a REST shim instead of the Atlassian Remote MCP: the hosted MCP
(mcp.atlassian.com) requires an interactive, browser-based OAuth 2.1 flow
with dynamic client registration — it does NOT accept the stored Jira REST
OAuth token as a Bearer header, so it fails to connect from a headless
agent ("claude mcp list" → Failed to connect; no mcp__jira-server__* tools
load). The Jira REST API accepts the same stored token (it carries
write:jira-work), so comments go via POST /rest/api/3/issue/{key}/comment
on the cross-region api.atlassian.com/ex/jira/{cloudId} base.

- New `jira_reactions.py`: gated by channel_source=='jira' + required
  metadata; swallows all network/auth errors (comments are advisory, never
  gate the pipeline); auth circuit-breaker mirrors linear_reactions.
- Wired into pipeline.py at task start, normal finish (with PR url), and
  the crash path — parallel to the existing Linear reaction hooks.
- prompt_builder: Jira tasks now get NO MCP-comment addendum (the earlier
  Linear-only gate already skipped them); instructing the agent to use the
  non-loading MCP tools would just waste turns. Comments are out-of-band.

Adds test_jira_reactions.py (gate, ADF body, success/failure/PR variants,
error-swallowing, auth circuit breaker) and channel-addendum tests.

* fix(jira): repair botched merge in test_config.py imports

The 'Merge branch main' commit (c84cc66) left an invalid import block:
a missing comma after PR_WORKFLOW_IDS (syntax error) plus a stale
PR_TASK_TYPES import that main's aws-samples#248 removed from config.py. ruff
rejected the file, aborting the agentcore build.

Drop the orphaned PR_TASK_TYPES import and fix the comma.

* fix(jira): type _config base dict so ty accepts TaskConfig(**base)

test_prompts.py:_config built base from a homogeneous str literal, so ty
inferred dict[str, str] and rejected the spread into TaskConfig's
bool/int/list fields (17 invalid-argument-type errors). Annotate base as
dict[str, Any], matching the existing helper in test_runner.py. This
failure was previously masked by the lint syntax error that aborted the
build before typecheck ran.

* fix(jira): apply ruff format and resync stale docs mirrors

Three more issues that were masked behind the earlier lint/typecheck
failures, all surfaced once the build progressed to its 'fail on
mutation' gate:

- ruff format reflowed two long boolean/string lines in jira_reactions.py
  and test_jira_reactions.py that were committed unformatted.
- USER_GUIDE.md still referenced the retired `pr_review` task_type on the
  intro 'For example' line (a aws-samples#248 merge leftover); the rest of the guide
  uses `coding/pr-review-v1`. Fixed the source and regenerated the
  Starlight mirror (using/Overview.md).
- Quick-start mirror was missing the Node.js prerequisite line present in
  the QUICK_START.md source; docs-sync adds it.

Full `mise run build` now completes with no working-tree mutation.

* fix(jira): address PR aws-samples#302 review — security binding, token refresh, ADR/docs

Blocking (krokoko):
- Multi-tenant signature binding: webhook receiver flags stack-wide
  verification to the processor, which then ignores the body cloudId and
  binds to the sole active tenant (drops when ambiguous). CLI no longer
  mirrors the stack-wide secret into new per-tenant bundles; stack-wide is
  seeded once from the first tenant. Missing-timestamp replay skip is logged.
- Renumber ADR-014 -> ADR-015 (collides with workflow-driven-tasks); rewrite
  to the implemented REST-outbound reality (status accepted), correct dedup
  key, binding + refresh-ownership sections. Reconcile JIRA_SETUP_GUIDE,
  USER_GUIDE ("six ways"), ROADMAP, channel_mcp.py (placeholder + in-band
  log), jira-webhook-processor.ts, jira-integration.ts, agent.ts.
- Fix non-existent CLI command in feedback: onboard-project -> map
  <cloud-id> <project-key> --repo (processor + CLI next-steps hint).
- Implement notifyJiraOnConcurrencyCap (Linear parity) so the orchestrator
  IAM grant is used and Jira users aren't silently dropped on the cap.

Significant (ayushtr):
- Agent never refreshes the Jira token (Atlassian rotates refresh_tokens;
  agent has GetSecretValue only). Use the Lambda-written token verbatim and
  fail closed when expiring; Lambda path owns all refreshes.
- ADF media nodes (external images) now render to markdown so attachment
  extraction works; ADF->markdown computed once and reused.

Minor: one-sided clock-skew-tolerant timestamp freshness, base64-body guard,
replay window 24h->1h, resolveSoleTenantCloudId Scan comment.

Tests: agent no-refresh/fail-closed suite, multi-tenant binding tests,
base64/missing-timestamp/stack-wide-flag webhook tests, ADF media-node test,
notifyJiraOnConcurrencyCap parity suite. Docs mirrors regenerated.

Relates to aws-samples#288

* fix(docs): repair botched main-merge in sync-starlight.mjs

The 'Merge branch main' commit (0f47343) dropped the closing ');' on the
Jira mirrorMarkdownFile() call where it interleaved with main's new
'Deploy preview screenshots' mirror block, producing a SyntaxError that
broke the //docs:sync build step (and thus the whole build job).

* fix(cdk): repair botched main-merge in agent.ts

The 'Merge branch main' (0f47343) dropped the closing '});' on the
JiraWorkspaceRegistryTableName CfnOutput where main's new
GitHubScreenshotIntegration block was spliced in, cascading into ~40
TS1005 errors and breaking //cdk:compile.

* fix(cdk): correct DynamoDB table-count assertion + import ordering

Collapse the duplicated 17/14 table-count assertions left by an earlier
botched main-merge into a single correct count of 18 (17 enumerated
tables incl. the 4 Jira tables, plus github-webhook-dedup from
GitHubScreenshotIntegration). Also fix import ordering (github before
jira) flagged by eslint import/order.

* fix(jira): post Lambda-side feedback to api.atlassian.com gateway base

The Lambda-side Jira feedback helper built its REST URL from the tenant
site host (`*.atlassian.net`), but the per-tenant 3LO token is minted
with `audience=api.atlassian.com` and is only valid against the gateway
base `https://api.atlassian.com/ex/jira/{cloudId}/rest/...`. Every
pre-container feedback comment (unmapped project, unlinked user,
concurrency-cap rejection, createTaskCore non-201) therefore 401'd
silently, since these comments are best-effort and swallow errors.

Build the URL from `cloudId` (already on `JiraFeedbackContext`) against
the gateway base — matching the agent-side path in jira_reactions.py —
and drop the unused `siteUrl`. Correct the misleading
jira-workspace-registry-table comment that called site_url a "REST base".

Adds jira-feedback.test.ts asserting the request host is
api.atlassian.com (never atlassian.net), plus encoding and
never-throws coverage.

* fix(jira): extract magic numbers into named constants

Resolves @typescript-eslint/no-magic-numbers eslint errors that were
failing the cdk:eslint build step. Mirrors the named-constant convention
already used by the Linear integration siblings.

* fix(jira): address review — HMAC empty-secret guard, verify tests, doc fixes

Resolves the blocking items and nits from the PR aws-samples#302 review.

Blocking:
- B1: route the Jira webhook signing secret through isUsableHmacSecret in
  both getJiraSecret (on fetch) and verifyJiraSignature (defense-in-depth),
  matching the Linear/Slack/GitHub invariant. A whitespace-only per-tenant
  secret was previously truthy and made HMAC(' ', body) forgeable.
- B2: add cdk/test/handlers/shared/jira-verify.test.ts (30 cases) covering
  verifyJiraRequestForTenant's four outcomes (verified/mismatch/revoked/
  no-per-tenant-secret), the strict-lookup rethrow, verifyJiraRequest
  rotation-refetch, empty/whitespace-secret rejection, and the one-sided
  timestamp freshness window (stale / far-future / within-skew). Mirrors
  linear-verify.test.ts; the multi-tenant trust boundary had no coverage.
- B3: rewrite the JiraWorkspaceRegistryTable docstring (and the matching
  jira-integration.ts comments) to describe the real oauth_secret_arn /
  Secrets Manager resolution path instead of the never-implemented
  provider_name / AgentCore Identity model.

Nits:
- Reword the stale "MCP token" comment in jira-webhook-processor.ts to the
  REST-outbound reality.
- Add ts-/py-silent-success-masking nosemgrep justifications to the
  best-effort swallows in jira-verify.ts, jira-oauth-resolver.ts (3), and
  jira_reactions.py, matching the Linear annotations.
- On a refresh PutSecretValue failure, no longer cache the rotated token
  (SM holds a stale refresh_token); invalidate the cache and escalate the
  log so the breakage surfaces promptly.
- URL-encode the cloudId path segment in jira-feedback.ts and both cloud_id
  and issue_key in jira_reactions.py (defense-in-depth; issueKey was already
  encoded on the TS side).
- Re-extract the inlined 512 into WEBHOOK_PROCESSOR_MEMORY_MB (AI007).

mise run build green: 2177 CDK + 355 CLI + 1090 agent tests passing.

Relates to aws-samples#288

---------

Co-authored-by: bgagent <bgagent@noreply.github.com>
Co-authored-by: Alain Krok <alkrok@amazon.com>
Co-authored-by: Sphia Sadek <isadeks@gmail.com>

* chore(cicd): specific bot token

* fix: update the token

…tate re-settles (aws-samples#247 UX.15b stress-caught)

Live re-verify of the UX.15 stuck-panel fix surfaced a second facet: the
epic panel BODY re-settled to ✅, but the parent REACTION stayed 👀.
Cause: rollup_posted_at was stamped at the FIRST completion, so on any
re-completion claimRollup fails → mirrorParentState is skipped → the
Linear reaction/state never re-mirror (👀→✅). extendOrchestration already
clears the claim on the extend path, but a CASCADE re-open never did.

- New clearRollupClaim store op: unconditional REMOVE rollup_posted_at
 (idempotent).
- cascadeRestack's re-open branch (a cascade that re-opens the epic with
 '🔄 updating' rows) clears the claim, so when the re-stacks finish the
 parent state re-settles 👀→✅.
- Fixed the stale code comment that falsely claimed restack completions
 're-fire reconcileTerminalChild'.
- Tests: reconciler 'cascade re-open clears rollup_posted_at' + store
 clearRollupClaim unit test.

Full CDK suite green.

…d ROOT (aws-samples#247 UX.11 stress-caught)

A @bgagent trigger that is itself a thread-reply had its ✅/❌ ack
SILENTLY dropped — the reconciler logged Linear's 'Parent comment must
be a top level comment' rejection (commentCreate rejects a reply whose
parentId is itself a reply; Linear threads are one level deep). The 👀
landed (reactions ignore thread depth) but the reply never posted.

- LinearCommentEvent.data gains typed parentId (the thread root for a
 reply).
- Both trigger paths now set channel_metadata.trigger_comment_id =
 data.parentId ?? data.id (the ROOT), while the 👀 still reacts on the
 actual comment the human wrote. handleStandaloneCommentTrigger gains a
 replyTargetId param. A top-level trigger's parentId is undefined →
 falls back to commentId (unchanged behavior).
- Regression test: thread-reply trigger → 👀 on the reply, reply target
 = the root.

Full CDK suite green.

…arPostResult refactor)

Brings 20 upstream commits onto the integration branch (additive-diff
deploy pattern), incl. the Jira Cloud integration (aws-samples#288/aws-samples#302) and the
linear-feedback LinearPostResult/retryable refactor (aws-samples#311/aws-samples#332).

8 conflicts resolved:
- linear-feedback.ts: kept both my aws-samples#247 comment-reaction helpers and
 upstream's LinearPostResult type; adapted 5 helpers (reactToComment,
 swapIssueReaction, transitionIssueState, upsertStatusComment, +
 orchestration-rollup) to the new graphqlRequest LinearPostResult
 contract via.ok. Fixed a latent bug the refactor surfaced:
 upsertStatusComment's 'ok ? id : null' would always report success
 (object truthy) — now reads.ok.
- agent/tests/test_repo.py: took upstream's hermetic harness as base,
 ported my 3 A4-stacking branch-name-verbatim tests onto
 make_task_config (#14 regression coverage preserved).
- fanout-task-events.test.ts: upstream's { ok: true } mock + kept the
 replyToComment mock.
- agent.test.ts: DynamoDB table count → 19 (14 base + 4 Jira + 1
 orchestration); verified live by the suite.
- DEVELOPER_GUIDE.md / ROADMAP.md: kept both additions; regenerated the
 Starlight mirrors via docs sync.

Compiles + lint clean; full CDK suite passes (195 touched-suite tests
incl. the 19-table assertion; the only non-zero exit is the global
coverage gate on partial runs).

… the parent panel (aws-samples#247 #57)

User-spotted gap: the parent epic panel never showed a combined preview
screenshot live. renderEpicPanel had the capability (combinedScreenshotUrl
+ the ![combined preview] embed) but no caller populated it — and the
screenshot pipeline never PERSISTED the URL (it parsed the Linear
identifier from the PR branch, posted a comment, and discarded the URL),
so there was nothing for the reconciler to read.

- screenshot-url.ts: new pure extractTaskIdFromBranch (taskId is the
 2nd segment of bgagent/{taskId}/{slug}).
- github-webhook-processor: persistScreenshotUrl writes screenshot_url
 onto the deploy task's TaskRecord (keyed by the branch taskId),
 conditional attribute_exists, best-effort, behind a new TASK_TABLE_NAME
 env var. TaskRecord.screenshot_url added.
- reconciler: resolveCombinedScreenshotUrl(integration.child_task_id) —
 one Get — passed as combinedScreenshotUrl to upsertEpicPanel ONLY on
 the all-terminal settle when an integration node exists.
- GitHubScreenshotIntegration: new taskTable prop → TASK_TABLE_NAME env +
 grantWriteData; wired taskTable.table in agent.ts.

Tests: extractTaskIdFromBranch (4); reconciler '#57 all-terminal +
integration node → embeds combined screenshot'. Full CDK suite green
(133 across the touched suites). Only meaningful for fan-out epics with
an integration node + a real UI deploy.

…aws-samples#247 #58 deploy-block)

Deploying #57 rolled the stack back on AWS::Logs::DeliverySource
'AlreadyExists': the agentcore-alpha Runtime auto-creates DeliverySource
+ Delivery + DeliveryDestination per loggingConfig, and a construct-path
rename across alpha builds churned BOTH the CFN logical IDs AND the
account-scoped DeliverySource/DeliveryDestination Names. Because those
Names are account-unique, CFN's create-before-delete on the churned ids
hits AlreadyExists and rolls the whole stack back. (Not a #57 bug — any
deploy was blocked.)

Fix: pin the 4 account-name-unique log resources (2 DeliverySource +
2 DeliveryDestination) to their DEPLOYED logical IDs + Names via
overrideLogicalId + addPropertyOverride('Name', …), so CFN sees them as
the SAME resources and updates in place (diff: [~] DependsOn-only, no
replacement). The 2 CfnDelivery links have no Name and Ref the pinned
ids → harmless replace. Log delivery is stateless routing config.
Best-effort tryFindChild so a future alpha rename silently no-ops.

cdk diff confirms: Source/Dest = [~] in place (no AlreadyExists);
Delivery = [-]/[+] harmless. agent.test.ts (44) green.

 deploy-block, round 2)

Round-1 pinning fixed the DeliverySource/DeliveryDestination collision —
all 4 updated in place — but the rollback just moved one resource
downstream to AWS::Logs::Delivery ('identifier null already exists').
A Delivery has no Name, but it IS unique per (source, destination) pair;
with the source+dest now pinned, the churned Delivery logical id tried to
create-before-delete a SECOND link over the same pair → AlreadyExists.

Pin the 2 Delivery links' logical IDs too (logical-id only — no Name).
pinLogResource's liveName is now optional. cdk diff: all 6 log resources
[~] in place (Delivery no longer [-]/[+]); the inner [-]/[+] is just
DependsOn reordering. agent.test.ts (44) green.

… + panel preview deep-links (aws-samples#247 UX.16 + UX.17)

Live-caught on the ABCA-301 fan-out epic: the synthetic integration node
has NO Linear sub-issue of its own, so its work spilled THREE standalone
comments onto the PARENT epic — '🤖 Starting integration…', '🔗 PR
opened: aws-samples#191', '🖼️ Preview screenshot' — a comment stream that violates
the locked 'one maturing panel, no comment stream' spec and 100%
duplicates what the panel already shows (Integration row ✅ + Combined PR
+ Combined preview). Separately, the panel's combined preview embedded the
image but had no clickable link to the running combined deploy.

UX.16 — stop the flood (two emitters):
- agent: prompt_builder._channel_prompt_addendum now returns '' when
 channel_metadata has no linear_issue_id. The integration node is the
 only Linear task without one (orchestration-release omits it on
 purpose), so the agent no longer gets the 'post Starting/PR-opened to
 Linear' instructions → no groping onto the parent. Real sub-issues are
 unaffected (they have linear_issue_id).
- screenshot pipeline: persistScreenshotUrl now returns whether the deploy
 task is an integration node (read from the UpdateItem ALL_NEW
 channel_metadata.orchestration_sub_issue_id — no extra Get), and the
 processor SKIPS the standalone Linear screenshot comment for it. The
 GitHub PR comment still posts (load-bearing on the PR); the panel embed
 is the only Linear surface for the combined result.

UX.17 — panel preview deep-link:
- persist screenshot_preview_url (the live Vercel/Netlify deploy URL the
 shot was captured from) alongside screenshot_url; thread it through
 resolveCombinedScreenshotUrl → upsertEpicPanel → renderEpicPanel.
- the panel's combined preview is now a clickable linked image
 ([![combined preview](png)](preview)) + an 'Open the combined preview'
 link. Falls back to the plain image when no preview URL is known. The
 preview URL is payload-derived → parens percent-encoded (markdown
 breakout defense, same as the screenshot comment renderers).

Tests: agent test_linear_integration_node_gets_no_addendum (+ existing
linear test now carries linear_issue_id); processor 'persists BOTH urls'
+ 'integration node deploy persists but posts NO standalone Linear
comment'; renderEpicPanel deep-link + paren-encode + fallback; reconciler
#57 test extended to assert the deep-link. Also refreshed 8 stale
postRollup mocks to the merged LinearPostResult {ok} contract (merge
left them returning bare booleans → 5 pre-existing reds, now green).
cdk:compile clean; agent suite 1116 green.

…to the sub-issue they name (aws-samples#247 UX.18)

Live-caught on ABCA-304: a reviewer commented '@bgagent for the footer
can you change it to...' on the PARENT epic (the maturing panel lives
there, so that's the natural place to comment) and it was SILENTLY
DROPPED. The parent epic has no PR of its own, so the comment-trigger
fell through to the standalone GSI path, found no task for the parent
issue, and ignored it ('issue has no ABCA task — ignoring').

Fix: in handleCommentTrigger, detect when the commented issue is itself
an orchestration PARENT (deriveOrchestrationId(issueId) loads an
orchestration whose meta.parent_linear_issue_id === issueId — a pure
hash, so the parent's own id maps to its orchestration; a sub-issue's
doesn't). Route to handleParentEpicCommentTrigger:
 - 👀 on the comment IMMEDIATELY — a parent comment is never silently
 dropped again.
 - parseParentNodeReference(instruction, children) picks the target
 sub-issue: Linear identifier (ABCA-305) wins outright, else a
 significant (non-noise) title keyword ('footer' → 'Add a site-wide
 footer'). Exactly one started node with a PR → iterate it via the
 shared iterateOrchestrationChild (same pr-iteration + cascade marker
 + threaded ✅/❌ reply as commenting on the sub-issue directly).
 - 0/ambiguous match, or matched node has no PR → post a threaded reply
 on the parent: a best-effort 'did you mean <X>?' suggestion, the list
 of sub-issues + how to target one (@bgagent ABCA-123:...), and the
 'create a sub-issue for NEW work' path. NEVER auto-creates an issue
 and NEVER silently drops (user's call: ask, don't create).

Refactor: extracted the per-child iteration into iterateOrchestrationChild
(skipAck/prNumber params) so the direct sub-issue path and the new
parent path share one code path.

New pure module orchestration-parent-comment.ts (parseParentNodeReference
+ suggestClosestNode + renderParentDisambiguationReply), 16 unit tests
incl. the exact live case. 4 handler-wiring tests (live case, identifier
targeting, ambiguous→ask, no-match→ask). Existing A6 sub-issue +
standalone trigger tests unchanged + green (36→40 in the orch suite).
cdk:compile clean.

…et (aws-samples#368) (aws-samples#372)

Admin-UI Jira webhooks omit cloudId, so the receiver verifies against the
stack-wide secret. But `bgagent jira setup` only seeds that secret when it
looks unconfigured, and its heuristic (`!startsWith('{')`) misread CDK's
bare-string auto-generated value as operator-set — so the pasted secret was
never applied and every delivery failed HMAC with a silent 401.

- CDK: give the WebhookSecret an explicit JSON placeholder via
  generateSecretString, carrying a marker key, so the value genuinely
  starts with '{' as the CLI assumed.
- CLI: recognize the placeholder by its marker key (parse + key check)
  instead of the fragile startsWith('{') shape heuristic; a malformed or
  markerless value is treated as operator-set.
- Add CLI + CDK construct tests covering the placeholder cases, plus
  coverage for adjacent jira.ts/linear.ts helpers pulled into the
  coverage denominator by the new test imports.
- CI: use gitleaks-safe test fixture strings and cover openBrowser
  platform branches so branch coverage stays above threshold on Linux.

Migration: stacks deployed before this change keep their bare-string
placeholder (CFN regenerates secret values only on create), so they must
redeploy before setup will seed; documented in code + PR.

Co-authored-by: bgagent <bgagent@noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

…-routed iteration's ✅/❌ reply lands (aws-samples#247 UX.19)

Live-caught on ABCA-304 immediately after UX.18 shipped: a comment left
on the PARENT epic was routed to the footer sub-issue and an iteration
spawned (👀 ack + 'routed to sub-issue … pr_number 193'), but the
iteration then FAILED (transient GITHUB_UNREACHABLE) and NO ❌ reply
appeared — the human saw 👀 then silence.

Root cause: replyToIterationComment posted the ✅/❌ reply with
issueId = changedSubIssueId (the sub-issue, ABCA-305), but the trigger
comment lives on the PARENT epic (ABCA-304). Linear's commentCreate
rejects a threaded reply whose parentId belongs to a different issue, so
the reply silently failed. (The cascade-skip on FAILED was correct; the
reply, which runs BEFORE the success gate, was the casualty.)

Fix: thread trigger_comment_issue_id (the issue the human actually
commented on) through channel_metadata —
 - iterateOrchestrationChild adds it (defaults to the sub-issue id; the
 parent-epic path passes snapshot.meta.parent_linear_issue_id).
 - parseTerminalTaskRecord reads it into TerminalTaskEvent.
 - replyToIterationComment uses it as commentCreate's issueId, falling
 back to changedSubIssueId for pre-UX.19 tasks.
Direct sub-issue comments are unaffected (issue id == sub-issue). The
standalone fanout reply path already replies on linear_issue_id = the
comment's own issue, so no change needed there.

Tests: reconciler 'PARENT-routed iteration replies on the PARENT issue
not the sub-issue'; webhook wiring asserts trigger_comment_issue_id =
the parent. 78 green across reconciler+webhook+matcher suites.

…stop webhook-redelivery reply spam (aws-samples#247 UX.20)

CRITICAL live-caught: a no-match @bgagent comment on the parent epic
spammed 50+ duplicate disambiguation replies. Root cause: the UX.18
parent-comment handler posts its reply (and 👀) with NO idempotency
guard, and Linear REDELIVERS a comment webhook whenever the handler
exceeds its ~5s ack window (this path does several Linear API calls and
ran 7.7s). Each redelivery re-ran the whole handler → another reply. The
iteration path is deduped by ack_replied_at; the disambiguation path I
added in UX.18 had nothing. (Mitigated live by throttling the Linear
receiver+processor Lambdas to 0 concurrency; 49 spam comments deleted.)

Fix: new store op claimCommentAck — a conditional create-once write keyed
on (orchestration_id, 'ack#<commentId>') with a TTL, mirroring claimRollup.
handleParentEpicCommentTrigger claims BEFORE any side-effect; only the
first delivery proceeds (👀 + match/route/reply), redeliveries no-op. The
marker self-expires via the table's existing ttl attribute.
loadOrchestration now excludes any 'ack#…' (and any '<kind>#' marker) SK
from the children list so the dedup rows can't be mistaken for sub-issues
(real child SKs are UUIDs or '…__integration', never contain '#').

Tests: claimCommentAck (first-wins / redelivery-loses / error-propagates);
loadOrchestration excludes ack# rows; webhook 'redelivery posts EXACTLY
ONE reply' + 'matched iteration dedups to one task'. 58 green across
store+webhook suites.

…he self-reply loop (aws-samples#247 UX.20 root cause)

The 50-reply spam was NOT webhook redelivery (my first UX.20 theory) — it
was a genuine INFINITE SELF-TRIGGER LOOP: the parent-epic disambiguation
reply embeds a literal example '@bgagent ABCA-123: <what to change>'. That
reply is itself a Linear comment → fires a Comment webhook →
parseCommentTrigger's /@bgagent/ regex matched the mention INSIDE the
bot's own reply → posted another disambiguation reply (also containing
@bgagent) → … ~50 deep. Each iteration was a NEW comment with a NEW id, so
the per-comment ack-claim (UX.20 round 1) couldn't dedup it — it guarded
redelivery, not self-reference.

Root fix (the guard the Linear path never had — Slack already skips its
own bot_id messages to avoid exactly this): parseCommentTrigger now
returns NOT-triggered for any comment whose trimmed body starts with one
of the bot's own template markers (👋 ✅ ❌ ⚠️ 🔄 🤖 🖼️ 🔗) — exported
isBotAuthoredComment. The bot can never act on a comment it authored,
regardless of what example text the body contains. The pre-existing A6
trigger never looped only because the agent's progress comments happen
not to contain @bgagent; UX.18's reply was the first bot comment that did.

The UX.20-round-1 ack-claim (claimCommentAck) stays — it's still correct
defense against genuine webhook redelivery; this is the orthogonal,
primary fix for self-reference.

Tests: the EXACT spam body (👋 + embedded @bgagent example) → not
triggered; every template prefix → bot-authored; a real human @bgagent →
still triggers; leading-whitespace marker still caught. 41 green across
trigger+webhook suites.

…ation done — 👀→✅/❌ + In Review (aws-samples#247 UX.21)

User-caught, three symptoms one cause: after a comment-iteration finishes,
(1) the trigger comment stayed on 👀 forever (never ✅), (2) the sub-issue
state flapped In Progress/In Review, and (3) the panel showed ✅ (correct,
reads child_status) while the sub-issue said In Progress — three views
disagreeing. Root cause: the reconciler posted the threaded ✅/❌ reply but
never settled the comment REACTION or the sub-issue STATE; state was
delegated to the AGENT via a prompt instruction (non-deterministic, raced,
got stuck).

Fix: the platform now owns settlement (as it already does for the parent
epic's reaction/state). In replyToIterationComment, after the reply:
 - swap the TRIGGER comment 👀 → ✅ (success) / ❌ (failure) so the comment
 reads done at a glance, not just the threaded reply.
 - on success, advance the SUB-ISSUE to In Review (PR updated & open,
 awaiting human merge — same convention the epic uses; user's choice).
 On failure, leave the state (never demote). The reaction/state target
 the actual trigger comment + the iterated sub-issue, so a parent-routed
 comment settles the parent's comment + the footer sub-issue correctly.
Gated once-only by the existing ack_replied_at claim; both helpers are
idempotent (re-converge to one marker / skip if already in target state).

New helper swapCommentReaction (mirrors swapIssueReaction but on a COMMENT
— queries comment(id){reactions}, deletes stale bgagent markers, adds the
target; never touches a human reaction). Tests: helper (swap/idempotent/
human-safe/no-token) + reconciler success→✅+In Review, failure→❌+no
transition. 80 green across linear-feedback + reconciler suites.

…d migration shim (no more hardcoded-into-every-stack)

User flagged the hardcode: the #58 fix pinned backgroundagent-dev's live
CloudFormation logical IDs + account-unique Names directly into agent.ts,
applied UNCONDITIONALLY. The old comment falsely claimed a fresh stack
"just deploys clean" via tryFindChild no-op, but the children DO exist on
every stack, so it would force ANY stack (a fresh deploy, another account,
CI, this code on main) to adopt the dev stack's identities. Wrong.

Why the pins exist at all: only a stack deployed BEFORE the agentcore-alpha
bump has pre-existing churned resources to collide with (AlreadyExists on
create-before-delete). A fresh stack has nothing to collide with and MUST
synth the current alpha's natural ids.

Fix: PINNED_LOG_DELIVERY_BY_STACK keyed by stackName (only
"backgroundagent-dev" listed) plus maybePinChurnedLogResources that
applies the overrides ONLY when the running stackName matches (or a
"-c pinnedLogDeliveryStack=name" context selects it). Every other stack
gets no overrides and a pristine synth. Verified: real backgroundagent-dev
synth still pins (deploy stays unblocked); a different stack name synths
natural alpha ids. Delete the table entry + helper once the dev stack is
migrated. agent.test.ts (44) green.

… in gitleaks

CI secret-scan (gitleaks generic-api-key) false-positived on the
'orch_abc_SUB-1'-style idempotencyKey fixtures in the orchestration tests
(orchestration-release.test.ts / orchestration-reconciler.test.ts) — these
are made-up test values, not credentials. Scope a targetRules+paths
allowlist to those two test files, mirroring the existing wat-opaque-123 /
test-signing-secret-abc123 fixture exemptions. Range scan: no leaks found.

…#247 PR aws-samples#373)

CI 'build (agentcore)' failed on //agent:lint (6 ruff errors that landed
across the #1 build-command + upstream-merge commits, committed without
the agent lint gate passing):
 - E501 ×4: config.py _KNOWN_WRITEABLE_WORKFLOW_IDS, test_prompts.py
 restack-assert + workflow-id loop, test_verify_commands.py real-failure
 fixture → wrapped.
 - PLR2004: post_hooks.py magic 127 → new SHELL_COMMAND_NOT_FOUND const.
 - SIM108: repo.py if/else default_branch → 'or' expression.
Then applied ruff format (the CI self-mutation guard enforces format, not
just check) — normalized config.py/repo.py/test_repo.py/test_verify_commands.py.
ruff check + ruff format --check both clean; agent suite 1116 green.

… debug printer (aws-samples#247 PR aws-samples#373 CodeQL high)

CodeQL flagged py/clear-text-logging-sensitive-data (HIGH) at
scripts/orchestration_debug.py:53 — the parent-meta printer derived
has_oauth via m.get('linear_oauth_secret_arn'), which READS the secret
ARN value (CodeQL's taint source) even though only 'yes'/'no' is printed.
The secret never actually reached output, but the value-read started the
taint. Fix: test KEY PRESENCE ('linear_oauth_secret_arn' in m) so the
secret string is never accessed at all — no taint source, and the printed
line provably logs only the parent issue id, repo, user id, and a
presence flag. Debug-only script (DynamoDB pretty-printer), not prod code.

Resolves the 1 high-severity CodeQL alert on PR aws-samples#373.

…nted false positive (aws-samples#247 PR aws-samples#373)

User chose to leave the HIGH py/clear-text-logging-sensitive-data alert
red + document it (it's a dev-only debug printer; logs only ids + a
yes/no oauth-present flag, never the secret value). Keep the key-presence
check ('in m' — secret value never read) but correct the comment: CodeQL
still flags it because it taints the whole stdin dict and follows any
s(m,…) read into a print. Documented in PR aws-samples#373's 'before merge' list for
a maintainer to dismiss.

…aws-samples#247)

CI 'build (agentcore)' failed on //cdk:eslint with 24 problems. Fixes:

SOURCE (real named constants for no-magic-numbers):
 - MAX_IDEMPOTENCY_KEY_LENGTH (128) for the 3 synthesized idempotency-key
 slices (linear-webhook-processor ×2, orchestration-reconciler restack).
 - DDB_BATCH_WRITE_MAX_ITEMS (25) + ORCH_ID_HASH_HEX_LENGTH (32) in
 orchestration-store; MIN_ABCA_BRANCH_SEGMENTS (3) in screenshot-url;
 DLQ_RETENTION_DAYS (14) + SWEEP_TIMEOUT_MINUTES (5) in the two
 reconciler constructs.

TESTS (config intent): extend the existing test-file eslint override —
which already turns off no-magic-numbers for test/**/*.ts — to also relax
max-len and no-shadow (tests legitimately have long fixture/assertion
lines and reuse small helper names like `row`/`makeDdb` across sibling
describe blocks). Acknowledged the e2e Promise.all over a fixed 2-element
array with the cdklabs/promiseall disable.

Also folds in eslint --fix reformatting (multi-line object/import
expansion) across the orchestration test + handler files so the tree
matches post-fix output (CI's self-mutation guard requires this).

NOTE: one eslint error remains on CI — import-x/no-unresolved for
@aws-cdk/integ-tests-alpha in test/integ/integ.task-api-smoke.ts. That
file is BYTE-IDENTICAL to upstream/main (green there) and the dep IS
declared in package.json; the error is a node_modules cache/install
artifact (the alpha dep wasn't in CI's restored cache). Verified locally:
a fresh `yarn install` fetches the dep and cdk eslint is fully clean.

agent ruff + cdk compile clean; affected suites 137 green.

…ruff's frozenset formatting (aws-samples#247 PR aws-samples#373)

The workflows contract test (CDK descriptors ↔ agent config) parses
_KNOWN_WRITEABLE_WORKFLOW_IDS out of agent/src/config.py with a regex that
required frozenset((…)) with adjacent parens. When the earlier lint pass
ran ruff format on config.py it expanded the frozenset to multi-line
(frozenset(\n (\n "…",\n )\n)), so the regex returned null and the
test failed (1 of 2574). Fix: tolerate whitespace between the parens
(frozenset\(\s*\(…\)\s*\)) so it matches either single- or multi-line
formatting. 21 workflows tests green; regex verified against the live
config.py shape.

…st-GA) interaction channel (#56)

Design-only scoping of the actor=app / agent-session migration. Records:
- VERIFIED LIVE (2026-06-17): both deployed workspace tokens carry
 'read write app:assignable app:mentionable' → bgagent is already an app
 actor; the auth half of the migration is DONE, zero work.
- Linear is an interaction layer, not compute — switching changes trigger
 + status display only; all compute stays on ABCA's AgentCore/ECS.
- GO/NO-GO: adopt agent sessions as an ADDITIONAL flag-gated trigger/ack
 channel ONCE Linear GAs the Agents API (currently Developer Preview),
 reusing the channel-agnostic aws-samples#247 engine. Do NOT rip out the now-hardened
 comment path. The win is real but partial — it retires the brittle
 string-match-trigger + hand-rolled-ack seam, but the parent-epic panel /
 cascade / base-branch engine stays ours (no native cross-issue rollup).
- Activity model (thought/action/response/elicitation/error + session
 states) maps cleanly onto the ack states aws-samples#247 already built.

Includes the regenerated Starlight mirror (docs:sync). No code changes.

….24)

Time-boxed no-infra spike against the deployed app-actor token:
- API reachable: agentActivityCreate, agentSessionCreateOnIssue,
 AgentSession type, AgentActivityType enum all present + match docs.
- agentActivityCreate accepts our {agentSessionId, content:{type:thought,
 body}} input (failed only on session-id lookup, not schema) — ack-emission
 half proven callable.
- BLOCKER (config, not code): agentSessionCreateOnIssue → 'Agent sessions
 are not enabled for this application'. App needs the 'Agent session events'
 webhook category enabled in Linear Application settings (app-owner action).
- 10s-ack-vs-long-compute risk not yet proven E2E (needs a real session id,
 gated on enablement) — but its components are confirmed callable.
Throwaway issue created + deleted; app token scrubbed. No migration code.

…ong-compute risk (UX.24)

After the app owner enabled 'Agent session events':
- agentSessionCreateOnIssue now succeeds (status active).
- 10s risk RESOLVED: thought at t+0 → active, then a 14s no-activity gap →
 STILL active (not stale). The 10s rule is initial-ack-only; our webhook
 emits the thought synchronously like today's 👀, then the >10s async spawn
 proceeds — no architectural conflict.
- Full lifecycle derives: thought/action→active, response→complete,
 elicitation→awaitingInput, error→error (all 5 types accepted; states
 auto-derive). Maps 1:1 to the aws-samples#247 ack model.
Remaining gate for an additive channel is the per-issue-session vs
cross-issue-epic-rollup gap + Preview→GA wait, NOT a technical blocker.
Spike issues created+deleted; token scrubbed; no migration code.

…ation + log delivery (aws-samples#595)

* fix(bootstrap): grant route53resolver:UpdateFirewallRuleGroupAssociation to exec role

Live-caught deploying the ECS substrate to dev (--context compute_type=ecs): the
CFN execution role got AccessDenied on route53resolver:UpdateFirewallRuleGroup-
Association, failing DnsFirewall/RuleGroupAssociation and rolling back the stack.

The bootstrap policy already grants Associate/Disassociate/Get/List on the
firewall rule-group association but not Update. That action is only exercised
when CFN does an in-place UPDATE of the existing association (e.g. coming out of
a rollback, or any change that rewrites the resource) — a fresh create or a
no-op update never hits it, which is why it went unnoticed until now. Classic
least-privilege bootstrap drift (same class as aws-samples#402/aws-samples#404/aws-samples#407/aws-samples#409), NOT an ECS-
or branch-specific issue: main lacks the action too; deploying the ECS path just
exercised the update path that surfaces it.

Not added: the non-fatal s3:Get*/TagResource read-sweep denials CFN's S3 handler
emits — those are tolerated (no S3 resource failed), and granting describe-handler
breadth for unused bucket features would bury real gaps (the aws-samples#406 lesson).

Regenerated bootstrap artifacts + updated the DEPLOYMENT_ROLES.md golden and its
Starlight mirror. Full cdk suite green (125 suites / 2289 tests).

(cherry picked from commit f69f01a)

* fix(bootstrap): grant logs:UpdateDeliveryConfiguration to exec role

Live-caught deploying to dev: the CFN execution role got AccessDenied on
logs:UpdateDeliveryConfiguration updating RuntimeApplicationLogsDelivery
(AWS::Logs::Delivery), which failed the stack update AND its rollback → the stack
landed in UPDATE_ROLLBACK_FAILED.

The observability bootstrap policy grants CreateDelivery + the LogDelivery family
(Create/Get/Update/DeleteLogDelivery) + Put/Get/Delete DeliverySource/Destination,
but not UpdateDeliveryConfiguration. That action is only exercised when CFN does an
IN-PLACE update of an existing AWS::Logs::Delivery resource — a fresh create never
hits it, so it went unnoticed until a stack that already had the delivery resource
was updated. Same least-privilege bootstrap-drift class as aws-samples#402/aws-samples#404/aws-samples#407/aws-samples#409 and
the route53resolver:UpdateFirewallRuleGroupAssociation fix on this branch.

NOT an ECS- or branch-specific gap: verified logs:UpdateDeliveryConfiguration is
absent on main and linear-vercel too, and this branch does not touch the delivery
resource or observability.ts — the ECS deploy-verify merely exercised the update
path that surfaces the latent hole.

Regenerated bootstrap artifacts + updated the DEPLOYMENT_ROLES.md golden and its
Starlight mirror. Full cdk suite green (125 suites / 2289 tests).

(cherry picked from commit 1697c38)

… beforeEach (#115) (aws-samples#602)

hydrateContext falls back to process.env.MEMORY_ID when no memoryId option is
passed (context-hydration.ts:990). The test 'excludes memory_context when
memoryId is not provided' asserted loadMemoryContext is NOT called — but if
MEMORY_ID leaked into the jest process env (another test file, or the deploy
env when the suite runs in-container), the source picked it up and DID call
loadMemoryContext, failing the assertion. Order/environment-dependent flake:
green locally (no MEMORY_ID), red on the fork's in-container build.

Consequence: the flake blocked the pre-push hook, so the fork agent bypassed
its own gate with `git push --no-verify` on BOTH ABCA-487 and ABCA-488.

Fix: `delete process.env.MEMORY_ID` in beforeEach so every test starts from a
clean no-ambient-memory baseline; tests that want memory pass the memoryId
option explicitly (no test relies on the env fallback). Verified: the suite now
passes 92/92 both with MEMORY_ID set in the env (the container condition) and
without. Full build green (cdk 2853).

# Conflicts:
#	cdk/src/handlers/orchestrate-task.ts

…k-v1, not default/agent-v1 (aws-samples#594)

* fix(workflows): repo-bound task w/o workflow_ref → coding/new-task-v1, not default/agent-v1

aws-samples#296 (workflow-driven tasks) replaced the task_type→workflow mapping with a
resolution ladder, but left the repo-aware rung ('Phase 4') unwired. Every
task with no explicit workflow_ref — all Slack tasks and all aws-samples#247
orchestration children (neither sets one) — fell through to the platform
default default/agent-v1: the freeform, repo-less agent prompt with NO
git/PR discipline. The agent then improvised (gh api / gh pr create against
an empty local clone), so ensure_pr found no commits and recorded
pr_url=null, screenshot→Linear routing lost its branch signal, and aws-samples#247 A4
stacking broke (children couldn't fetch the unpushed predecessor branch).

Re-wire the missing rung minimally: resolveWorkflowRef takes hasRepo; an
absent ref with a repo present resolves to coding/new-task-v1 (the
disciplined coding workflow — edit locally, commit, push, platform opens
the PR via ensure_pr), matching pre-aws-samples#296 behaviour. Repo-less tasks still
default to default/agent-v1. An explicit workflow_ref always wins. The
single create-task-core call site passes Boolean(body.repo), so both Slack
and orchestration (which create via createTaskCore with repo set) inherit
the fix. Upstream regression — worth an upstream issue too.

Updated workflows + create-task-core tests; the old test asserting
default/agent-v1 for a repo task encoded the regression.

(cherry picked from commit 99b5a17)
(cherry picked from commit 9d8b25d)

* refactor: pin coding workflow at channel call sites, not the resolver default

Rework per review (aws-samples#594): follow the merged aws-samples#547 precedent instead of changing
the shared resolver default. A repo-bound channel task must run the disciplined
coding workflow (clone → commit → push → platform opens the PR), not the
repo-less default/agent-v1 that records pr_url=null — but that "repo task ⇒
coding workflow" decision now lives explicitly at each channel's createTaskCore
call site rather than as an implicit resolver-level inference.

Addresses the review point-by-point:

- B3(a): revert resolveWorkflowRef to its single-arg form (no hasRepo); pin
  workflow_ref: CODING_WORKFLOW_ID in the Linear and Slack processors, mirroring
  the Jira processor (aws-samples#546/aws-samples#547). One visible decision per channel, uniform
  across all three. (No aws-samples#247-child path exists on main.)
- B2: moot — no resolver behaviour change, so WORKFLOWS.md / API_CONTRACT.md /
  USER_GUIDE.md all stay accurate. No doc edits, no mirror regen needed.
- N1: moot — the hasRepo param is gone, so the "forgot hasRepo" footgun can't exist.
- N2: promote the 'coding/new-task-v1' literal to CODING_WORKFLOW_ID next to
  DEFAULT_WORKFLOW_ID, with a module-load invariant asserting both ids exist in
  DESCRIPTORS (a descriptor rename now fails at import, not as a runtime
  TypeError). Jira's literal switched to the constant too — uniform.
- N3: moot — the stale "last rung" JSDoc was in the reverted resolver block.
- §6 test gap: create-task-core caller tests now assert the real behaviour
  (omitted ref → default/agent-v1, with AND without a repo — the symmetric
  repo-less case that was missing). Channel processor tests (Linear/Slack/Jira)
  assert each pins workflow_ref: 'coding/new-task-v1'.

Full cdk build green (compile + jest + eslint + synth).

…4) (aws-samples#601)

* fix(fanout): render the PR link on ✅ success, not only on ⚠️ (F-prlink)

The Linear completion comment rendered the PR URL ONLY on the ⚠️ "shipped a PR
but stopped early" path, on the assumption that on ✅ success the agent's own
step-2 "PR opened" comment reliably carries the link, so duplicating it is noise.

That assumption fails when the agent skips its PR-opened comment. Live-caught on
ABCA-584: a :decompose that declined to split ran as one coding task, opened PR
aws-samples#395 (pr_url + build_passed on the task record), but posted NO "🔗 PR opened"
comment — so the ✅ "Task completed" comment omitted the link and it was lost
entirely; the user asked "where is the PR link?".

Fix: render `PR: <url>` whenever the task produced one, on BOTH ✅ and ⚠️. The
completion comment is the terminal, platform-owned surface, so it must carry the
link rather than depend on the agent choosing to post its own; a duplicate with
the agent's comment (when it does fire) is far cheaper than a missing PR, and
this is the one terminal comment per task so it can't spam. Test updated to
assert the link renders on ✅. Full cdk build green (2935 tests). Held.

* docs+test: address review nits N1–N3 on the PR-link render

Optional polish from the aws-samples#601 review (fix itself approved, unchanged):

- N1: add a negative assertion for the branch this change now makes live —
  ✅ task_completed + prUrl null → NO `PR:` line. The relaxed `if (args.prUrl)`
  guard means this is no longer structurally guaranteed by the old ⚠️-only
  condition, so pin its absence (fanout-task-events.test.ts).
- N2: reword the "ONE terminal comment per task" comment — the single-post
  guarantee lives in the caller `dispatchToLinear` (linear_final_comment_event_id
  idempotency marker), NOT this pure formatter, which enforces nothing. Credit
  the right layer so a future non-idempotent caller isn't misled.
- N3: add a one-line note atop the function JSDoc — prUrl, when present, renders
  on ALL frames — so the "why" isn't split between the JSDoc (ABCA-91 story) and
  the render-site note (ABCA-584) 50 lines below.

No behavior change. fanout-task-events tests green (108); eslint clean.

…aws-samples#573) (aws-samples#603)

* feat(jira): post final status comments with cost, turns, and duration (aws-samples#573)

Mirror the Linear final-status fan-out for Jira. Jira-origin terminal
tasks now get a deterministic platform-side comment with outcome, cost,
turns, duration, task id, and the PR link — posted by the fan-out plane,
not the agent, so it fires even when the agent crashes before completing
(max-turns, OOM).

- fanout: add `jira` NotificationChannel + CHANNEL_DEFAULTS (terminal
  events + task_timed_out) + `dispatchToJira`, structurally mirroring
  `dispatchToLinear` (env guard -> load task -> channel_source gate ->
  metadata read -> post-once marker -> post). New renderer
  `renderJiraFinalStatusComment` emits ADF paragraphs with the same
  three-outcome framing (completed / shipped-but-stopped / failed); the
  PR link renders on the success path too (Jira has no other surviving
  PR-link surface once the agent terminal comment is demoted).
- jira-feedback: add `buildAdfDocument` (multi-paragraph ADF with
  strong/em marks) + `postIssueCommentAdf` returning a classified
  `JiraPostResult` (retryable vs terminal), reusing the 401 forced-
  refresh-and-retry-once path. `postIssueComment` keeps its boolean API.
- TaskRecord: add `jira_final_comment_event_id` post-once marker;
  TaskNotificationsConfig gains a `jira` channel.
- construct/stack: wire JiraWorkspaceRegistryTable +
  `bgagent-jira-oauth-*` Get/Put grant into FanOutConsumer (guarded).
- agent: demote the Jira terminal comment — remove
  `comment_task_finished` and its two pipeline call sites so fanout owns
  the terminal comment (no double-post); keep the start comment.
- docs: update JIRA_SETUP_GUIDE for the platform-side final comment.

Tests: fanout Jira success / failure / shipped-but-stopped / timed_out /
missing-metadata / non-Jira skip / idempotent retry / retryable escalation
/ marker persistence / missing-env; ADF builder + classified post result;
construct grant guards; agent terminal-comment-demoted guard.

* feat(jira): render the PR link in the final-status comment as a clickable hyperlink

ADF — unlike Linear's Markdown — does not auto-linkify a bare URL in a
plain text node, so the PR link in the Jira final-status comment rendered
as unclickable text the requester had to copy-paste.

Add an optional `href` to `AdfTextRun`; `buildAdfDocument` maps it to an
ADF `link` mark (composes with strong/em). The Jira final-status renderer
splits the PR line into a "PR: " label run + a URL run carrying `href`, so
it renders as a real hyperlink on both the ✅ and ⚠️ paths.

Tests: buildAdfDocument link-mark emission + href/strong composition;
renderer asserts the URL run carries the href.

* fix(jira): address aws-samples#603 review — reframe ✅ PR-link rationale, humanize task_timed_out header, match Linear bold scope

Review feedback on aws-samples#603 (all from isadeks' approve-with-notes):

1. Drop the "diverges from Linear" framing for rendering the PR link on
   the ✅ success path. The real reason is general (ABCA-584): the agent's
   own "PR opened" comment isn't guaranteed to fire, so the platform
   comment must always carry the link. aws-samples#601 lands the same fix for Linear,
   so this is no longer a Jira-specific divergence — reframed the docstring
   + renamed the test accordingly to avoid a stale-comment / semantic
   merge conflict with aws-samples#601.

2. Humanize the ❌ header subtype: strip `task_` AND turn underscores into
   spaces so `task_timed_out` renders "Task timed out", not the raw
   "Task timed_out". Jira is the only channel routing task_timed_out
   through this renderer, so it's a case the copied-from-Linear code never
   hit. Added a test.

4. Match Linear's ⚠️ bold scope: bold only through the reason and leave
   the trailing "— review and decide…" advice unbolded (two runs), instead
   of bolding the whole header. Added a test.

(#3 — adding task_timed_out to CHANNEL_DEFAULTS.linear for parity — is an
optional follow-up the reviewer flagged as out of scope; tracked separately.)

---------

Co-authored-by: Sphia Sadek <isadeks@gmail.com>

When `build`/`integ` complete on a PR, aggregate all check-runs + commit
statuses and either (a) comment which checks are failing (no review compute
spent), (b) auto-update an out-of-date branch so CI re-runs (PAT so build
re-fires), (c) comment asking to resolve conflicts, or (d) trigger the ABCA
coding/pr-review-v1 agent via the Task API webhook once green.

Comments-only, edit-in-place, per-SHA idempotent — does not touch Mergify or
the integ-smoke gate. Runs in the trusted base-repo context via workflow_run so
secrets/PAT are available for fork PRs; no PR code is checked out or executed.

Adds review-gate.yml to .github/zizmor.yml dangerous-triggers and
secrets-outside-env ignore lists (intentional workflow_run + repo-level secrets;
the gate has no environment/approval boundary).

…aws-samples#502) (aws-samples#503)

* fix(ecs): write task payload to S3, not inline overrides (aws-samples#502)

The ECS compute strategy inlined the full orchestrator payload (incl. the
large hydrated_context) into the AGENT_PAYLOAD container-override env var.
ECS RunTask caps the TOTAL containerOverrides blob at 8192 bytes, so any real
task was rejected before the container started:

  InvalidParameterException: Container Overrides length must be at most 8192

AgentCore is unaffected — it passes the payload in the InvokeAgentRuntime
request body, which has no comparable limit. The bug only surfaces with a
realistic hydrated payload, which is why the prior ECS smoke test (a small
Rust cargo-check, aws-samples#494) didn't catch it.

Fix — stash the payload out-of-band and pass only a pointer:
- New EcsPayloadBucket construct (mirrors TraceArtifactsBucket): BLOCK_ALL,
  enforceSSL, S3_MANAGED encryption, 1-day lifecycle TTL (payloads are
  ephemeral — read once at boot). Dedicated bucket so the ECS task role's S3
  read is scoped to payloads only and can't touch attachments/traces.
- ecs-strategy: when ECS_PAYLOAD_BUCKET is set, PutObject the payload to
  <task_id>/payload.json and pass AGENT_PAYLOAD_S3_URI in the override; the
  boot command fetches+parses it via boto3. Inline AGENT_PAYLOAD remains as a
  fallback (small payloads / no bucket), so nothing regresses. deleteEcsPayload
  helper removes the object.
- orchestrate-task finalize: best-effort deleteEcsPayload for ECS tasks once
  terminal (the container has long since read it); lifecycle rule is the
  crash backstop.
- EcsAgentCluster: accept payloadBucket, inject ECS_PAYLOAD_BUCKET env, grant
  the task role READ ONLY (untrusted repo code must not write/delete payloads;
  the trusted orchestrator owns write+delete). Session-role-aware.
- task-orchestrator: ecsPayloadBucket prop → grantPut + grantDelete to the
  orchestrator; @aws-sdk/client-s3 added to bundling externals.
- agent.ts: updated the commented uncomment-to-enable ECS scaffolding to wire
  the payload bucket.

Tests: new bucket construct (TTL/SSL/block-public/autoDelete); strategy
S3-write + URI-pointer + inline fallback + deleteEcsPayload (incl. best-effort
swallow + no-op without bucket); cluster read-grant + env var + read-only
(no put/delete). Full build green.

Closes aws-samples#502

* fix(ecs): remove dead ECS_PAYLOAD_OBJECT_KEY_PREFIX export (review B1)

The `export const ECS_PAYLOAD_OBJECT_KEY_PREFIX = ''` constant was referenced
nowhere — ecsPayloadKey() (ecs-strategy.ts) builds `<task_id>/payload.json`
independently and already documents that layout in its own docstring. The dead
export was a "prefix" whose value was '' with a docstring describing a key
layout it didn't produce, and it raised the knip dead-code count, tripping the
ratchet inside `mise run build`. Delete it; ecsPayloadKey remains the single
source of truth for the key layout.

---------

Co-authored-by: bgagent <bgagent@noreply.github.com>
Co-authored-by: Alain Krok <alkrok@amazon.com>

Operator walkthrough for wiring the review-gate workflow: register an ABCA
webhook (bgagent webhook create), set the ABCA_TASK_API_URL / ABCA_WEBHOOK_ID
repo vars and ABCA_WEBHOOK_SECRET secret, confirm the workflow is on the default
branch, and smoke-test. Covers the decision tree, fork-vs-same-repo update
behavior, opting PRs out, and troubleshooting (401/403, not-onboarded,
green-but-no-review, dismissed approvals).

Mirrors to using/ via sync-starlight (script entry + link route + sidebar slug),
and links from USER_GUIDE's webhook bullet. Docs build verified.

…gress (aws-samples#572) (aws-samples#605)

* feat(jira): transition originating issue across workflow as tasks progress

Move the originating Jira issue through its workflow so the board reflects the
task lifecycle: To Do → In Progress on start, → In Review on PR. Best-effort
only — logged and swallowed on any failure, sharing the existing 401/403 auth
circuit breaker, so the board never fails, blocks, or retries the task. Failed
tasks and tasks with no PR leave the status unchanged.

Status resolution ladder (per lifecycle point): per-project override
(--status-on-start / --status-on-pr) → safe heuristic (statusCategory
`indeterminate` on start, `In Review` name-match on PR) → skip with a warning.
Transitions requiring a screen and empty transition lists (no Transition Issues
permission) are skipped. No new OAuth scopes — read:/write:jira-work cover both
the transitions GET and POST.

- agent/src/jira_reactions.py: add transition_task_started / transition_pr_opened
  best-effort helpers; extract shared circuit-breaker accounting.
- agent/src/pipeline.py: invoke helpers at the start hook and the success-path
  PR hook (only when a PR was opened).
- cdk/src/handlers/jira-webhook-processor.ts: stamp optional
  jira_status_on_start / jira_status_on_pr from the project mapping into
  channel_metadata.
- cli/src/commands/jira.ts: add optional --status-on-start / --status-on-pr to
  `bgagent jira map`.
- docs/guides/JIRA_SETUP_GUIDE.md: Board transitions section (defaults,
  overrides, Transition Issues permission prerequisite) + troubleshooting.

Closes aws-samples#572

* fix(jira): address review — crash-safe transitions, Linear-parity selection

Addresses isadeks' review on PR aws-samples#605.

1. (correctness) _get_issue_transitions no longer raises AttributeError on
   valid-but-non-object JSON (null / bare list / scalar). Previously
   resp.json().get(...) could raise past the best-effort boundary, propagate
   out of the pipeline hook, and flip an otherwise-successful task to FAILED
   (worst case: after the PR opened). Now guarded with isinstance(dict).

2/3. (Linear parity) Rework transition selection to mirror the Linear
   reference (prompt_builder.py):
   - Start prefers a destination NAMED "In Progress" before the indeterminate
     category fallback — fixes the order-dependent bug where "Blocked" (also
     indeterminate) could be picked. The category fallback now excludes
     "Blocked".
   - PR prefers "In Review" then synonyms (Code Review / Review / Peer Review /
     Reviewing) then falls back to "In Progress", so a stock board or a
     Code-Review column isn't silently skipped.
   - Skip if the issue is already at/past the target category (won't drag a
     card backward on re-trigger). Fetches ?fields=status&expand=transitions
     to get current status + transitions in one call. Overrides bypass the
     already-past skip (deliberate instruction).

4. (hardening) CLI trims --status-on-start/--status-on-pr and treats
   whitespace-only as unset, so a fat-fingered blank can't persist a
   permanent no-op.

Tests: agent 43 (adds Blocked-vs-InProgress order, already-past skips, PR
synonym + In-Progress fallback, non-dict JSON parametrized); CLI adds trim +
whitespace-unset. Docs: resolution ladder rewritten to match. Full build green.

A Linear task against the full ABCA monorepo wedged silently for 50+ min:
the pre-agent baseline build (mise run build → the agent pytest suite) hung
on the ECS substrate, and the issue showed no reaction/comment/state the
whole time. Root-caused live on ABCA-707. Three fixes:

1. Kill the hang at its root (agent/tests/conftest.py). The ECS agent task
   def sets AGENT_SESSION_ROLE_ARN. With it set, aws_session resolves a
   *scoped* session and tenant_client returns session.client(...), which
   BYPASSES a @patch("boto3.client") mock. test_attachments then makes a
   REAL S3 get_object that blocks forever on the ECS network (no egress) in
   a socket read SIGALRM can't interrupt. Add AGENT_SESSION_ROLE_ARN to the
   _clean_env scrub list so every test resolves the unscoped path where the
   mock intercepts. reset_session_cache() alone was insufficient — a cold
   get_session() re-resolves scoped while the var is still set. + regression
   test (TestConftestScrubsScopingEnv).

2. Make the hang watchdog actually reap (agent/tests/conftest.py). The prior
   faulthandler.dump_traceback_later(1200, exit=True) never fired: pytest's
   faulthandler_timeout re-arms faulthandler's single timer per-test WITHOUT
   exit=True, cancelling the session-level exit timer. Replace with an
   independent daemon-thread reaper that dumps all stacks and os._exit(1)s at
   600s, so a future hang fails the build fast instead of burning to the
   3600s ceiling.

3. Early Linear ACK (agent/src/pipeline.py). Move token resolve + 👀 reaction
   + Backlog→In Progress + start comment to BEFORE setup_repo() so a
   large-repo task shows immediate feedback during the multi-minute baseline
   build instead of looking dead. As a side benefit, a setup-phase failure
   now has a 👀 for the existing outer crash handler to swap to ❌ — closing
   the silent-stuck-issue gap. configure_channel_mcp stays after the clone
   (it needs the repo dir).

aws-samples#614)

A follow-up `@bgagent <request>` comment on a completed Linear task that
opened no PR was silently dropped. handleStandaloneCommentTrigger is
iteration-only: on prNumber === null it checks for a clarify-hold and, if it
isn't one, returns with just an info log — the comment vanished.

But a task finishes PR-less in several real ways (no change needed,
failed-before-commit, or a question/investigation run), and a follow-up on
such an issue is almost always NEW work ("then just do X instead"), not
iteration. Add maybeStartStandaloneNewWork: when the repo + user are known
and the comment carries instruction text, dispatch a fresh coding/new-task-v1
against the same repo using the comment text as the description — reusing the
same 👀-ack + threaded reply + fanout terminal ownership as the iteration and
clarify-resume paths. Idempotency keyed newwork_<issue>_<comment>.

Edge cases: a bare `@bgagent` (no instruction) gets a threaded reply telling
the user what to do rather than a vague dispatch or silence; no repo / no
user_id falls through to the (now-narrowed) no-op log.

Tests: replace the obsolete 'NO PR → no task, no ack' case with the new-work
dispatch, bare-mention reply, no-repo, and no-user cases. Full cdk build green
(3118 tests).

Closes aws-samples#614.

…to-lv-2026-07-15

# Conflicts:
#	agent/src/pipeline.py
#	cdk/src/constructs/ecs-agent-cluster.ts
#	cdk/src/constructs/ecs-payload-bucket.ts
#	cdk/src/handlers/fanout-task-events.ts
#	cdk/src/handlers/shared/strategies/ecs-strategy.ts
#	cdk/src/handlers/shared/workflows.ts
#	cdk/src/stacks/agent.ts
#	cdk/test/constructs/ecs-agent-cluster.test.ts
#	cdk/test/handlers/shared/create-task-core.test.ts
#	cdk/test/handlers/shared/strategies/ecs-strategy.test.ts
#	cdk/test/handlers/shared/workflows.test.ts

…rror aws-samples#596 B1)

Mirrors the aws-samples#596 review B1 fix onto linear-vercel (this defect rode in via the
main→lv merge a9efaa6, which kept lv's version of the grant). coding/decompose-v1
delivers its plan via the assumed SessionRole (scoped to artifacts/${task_id}/*),
exactly like the AgentCore runtime whose task role has no direct artifacts grant.
The whole-bucket grantReadWrite over-privileged the untrusted-code role and broke
cross-task isolation. Task role keeps only the ARTIFACTS_BUCKET_NAME env; corrected
the inverted comment + the stale artifacts clause in the cdk-nag IAM5 reason. Test
flipped to assert the task role has NO s3:Put*/Delete* action. Full cdk build green.

The Task API validates Idempotency-Key against ^[a-zA-Z0-9_-]{1,128}$, but the
gate built it as `review-$REPO-$PR_NUMBER-$HEAD_SHA` where $REPO is `owner/repo`
— the "/" fails validation (and owner/repo + a 40-char SHA can exceed 128), so
the webhook returned 400 VALIDATION_ERROR and no review was ever triggered on a
green PR. Map disallowed chars to "-" and cap at 128; still per-(repo,PR,SHA)
unique. Verified live: bad key → 400, sanitized key → 201 (task created).

…rset (#48)"

This reverts commit 98fed6e.

This reverts commit 4466a02.

This reverts commit a746a9d.

…sient/service/user axis with auto-retry-once (aws-samples#599)

* fix(agent-classifier): recognize 'Agent session error (subtype=…)' wrapper

The error classifier keyed on `agent_status=error_max_turns` (pipeline.py's
wrapper) but missed runner.py:515's `Agent session error (subtype='error_max_turns')`.
A real max-turns failure fell through to UNKNOWN → 'Unexpected error'
(live-caught ABCA-483: a task hit the 100-turn cap but the Linear reply read
'Unexpected error'). The max_turns / max_budget / error_during_execution
patterns now match BOTH the `agent_status=` and `subtype=` wrappers.

Platform-agnostic, MAIN-BOUND (cherry-pick clean: single file +
colocated test, no Linear/orchestration coupling).

* feat(errors): 3-way transient/service/user classification + auto-retry-once on transient session-start

Error handling couldn't distinguish a transient hiccup from a real service error
— the retryable boolean conflated 'self-heals on retry' with 'you must change
something first', so a customer couldn't tell whether to retry or call their admin.

- error-classifier.ts: new ErrorClass axis (transient / service / user) on every
  classification. transient = infra/service hiccup a retry clears (ECS deploy-race,
  ENI/capacity delay, network blip, Bedrock throttle, concurrency cap); service =
  real platform/config fault an admin owns (bad token/scopes, model-not-enabled,
  blueprint misconfig); user = the request/code is the thing to change (build/test
  failed, guardrail, wrong PR, max-turns). retryGuidance() keys on errorClass and
  takes an autoRetried flag. New isTransientError() helper.
- orchestrate-task.ts: AUTO-RETRY-ONCE at session-start for transient failures —
  the one place a retry is idempotent by construction (no clone/commits/PR yet).
  Emits session_start_retry; stamps '[auto-retried]' so the surface says 'I tried
  again, still failed'. Mid-run crashes are NOT retried.

Backport note: the failure-reply.ts consumer hunk from the origin commit is
omitted — that module is part of the not-yet-merged aws-samples#247 orchestration UX and
does not exist on main. The classifier axis + auto-retry stand alone.

(cherry picked from commit 63a12dc)

* fix(errors): classify the claude Exec-format/broken-shim failure with retry guidance (ABCA-659)

When the agent image's claude CLI can't be exec'd (OSError Exec format error, or
the shim's own 'claude native binary not installed'), the classifier had no
matching pattern and fell through to the bare 'Unexpected error' with a generic
'report it' remedy — the exact no-guidance anti-pattern the error-feedback arc
(K5 buckets, remedy+retryable+errorClass) was built to eliminate. Live-caught on
ABCA-659's retry: the ❌ Linear comment just said 'Unexpected error', telling the
user nothing about whether to retry or escalate.

Add a COMPUTE + transient pattern so the failure reads honestly and actionably:
'Couldn't start the coding agent (environment issue) … not a problem with your
request … reply here to try again; if every attempt fails the same way, the
agent image needs a rebuild — contact your ABCA admin with the task id.' The
transient class also lets the platform's session-start auto-retry take a shot.
Matched before the AGENT/UNKNOWN fallthrough; two tests pin the copy + axis.

* feat(agent): stuck/runaway guard + surface the failure behind a max_turns cap (ABCA-662) (aws-samples#600)

* feat(agent): stuck/runaway guard — break a repeating-failing-command loop

Live-caught ABCA-483: a one-line README task burned ALL 100 turns (~22 min,
$1.53) because the agent re-ran the SAME failing command (mise //cdk:test →
JS-heap OOM, exit 134) over and over, yak-shaving the build env instead of
finishing. Nothing noticed until the hard max_turns cap killed it.

New `stuck_guard.py` (pure, dep-free): PostToolUse records each tool result;
a coarse (tool_name, command) signature tracks consecutive failures. A new
between-turns hook (registered after cancel, before nudge — same
short-circuit rationale) then:
 - STEER once at 3 repeats: inject 'stop retrying X — work around it or
 finish with what you have';
 - BAIL at 6 repeats: end the turn loop early (continue_=False) so the task
 fails fast instead of grinding to the cap.
Conservative by design: keys on a REPEATING FAILURE (not a raw turn count),
so a large task making varied progress never trips it; unknown tool output
counts as success. Fail-open everywhere — a guard bug can't wedge the agent.

Platform-agnostic, MAIN-BOUND: lives entirely in agent/src (stuck_guard.py +
hooks.py); surfaces via the channel-neutral error_message. The honest reason
is then rendered per-channel by the classifier / failure-reply (several fixes).

1158 agent tests pass (ruff + ty clean).

* fix: stuck-guard is advisory-only — drop the bail, keep a one-time steer

Reviewing the guard for false-positive risk (user: 'make sure the turn limit
isn't too aggressive') showed the bail path was unsafe: distinguishing a true
spin from a legitimately-iterating agent (re-running the same test command as
it fixes failures one by one) from raw output is genuinely fragile — a digit-
normalizing fingerprint that ignores volatile GC timings ALSO collapses
'test file_0' vs 'file_1' (the progress signal), so it would kill a working
agent. A false-positive KILL is far worse than a false-positive nudge.

So: removed BAIL entirely. The guard now only ever injects a ONE-TIME advisory
steer when the same command fails with IDENTICAL output N times; the max_turns
cap (with a fix's honest 'Exceeded max turns' reason) is the real runaway backstop.
A false positive costs exactly one extra advisory comment. Platform-agnostic,
main-bound.

* fix(agent): explain WHY a task hit max_turns + catch loop-of-variations early (ABCA-662)

ABCA-662 capped at max_turns, but the CAUSE was masked: it had finished the code
and then thrashed ~15 turns retrying a failing 'git push' (remote: invalid
credentials) every which way — a DIFFERENT command each turn, so the existing
per-signature stuck-guard (same command × identical output ≥3) never tripped,
and the terminal reason read only 'Exceeded max turns'. max_turns is a CORRECT
classification, but the user can't tell 'genuinely needed more turns' from 'spun
on an error' — and raising the cap just burns more tokens.

Two changes, both advisory (no hard kill — keeps the K10 no-false-kill stance):
- stuck_guard: add a signature-agnostic TRAILING WINDOW (last 6 tool outcomes).
  When ≥5 share the SAME byte-identical failure fingerprint across DIFFERENT
  commands, steer once ('you're spinning on one failing op — stop, it won't
  resolve by retrying'). EXACT fingerprint (no digit-blur) so a healthy
  iterate-and-fix loop (same cmd, a different test failing each run) never trips
  it — the K10 case, still covered by its test. Also exposes recent_failure_
  summary().
- pipeline/hooks: the between-turns hook latches that summary; the terminal path
  appends it to a max_turns reason → 'error_max_turns … — spinning on failing
  tool calls (last: git push → invalid credentials)'. Only enriches max_turns;
  a productive run adds nothing.
- error-classifier: a new bucket for 'error_max_turns … spinning on failing tool
  calls' → 'Ran out of turns while stuck on a failing step' with the honest
  remedy (raising --max-turns won't help; fix the failing op / check the env),
  ordered before the generic max_turns bucket. Tests: window-spin + K10 no-trip
  + summary + pipeline enrichment + classifier bucket.

* fix(errors): don't over-claim on a max_turns spin — offer BOTH remedies (ABCA-662 review)

The prior 'spinning on failing tool calls' classifier bucket asserted 'raising
--max-turns won't help'. That over-claims: the trailing window can't distinguish
(a) a HARD blocker no turn count fixes from (b) a LONG task that hit a
transient/recoverable snag near the end and just ran out — which is 662 itself
(siblings 661/663 pushed fine with the same token → its 'invalid credentials'
was a transient race that more turns / a retry WOULD have cleared). Reframe the
bucket to SURFACE what it was stuck on and present BOTH paths (environment
blocker → fix + retry; transient/recoverable or a shorter sibling got past it →
just retry / raise --max-turns), letting the failure KIND in the detail tell the
reader which applies. Title 'Ran out of turns retrying a failing step'. The
early window-steer (agent told to STOP and report while it still has turns) is
the real mechanism that lets a long task escape the thrash; this copy is just
the honest post-hoc explanation. Test updated to assert both remedies, not the
over-claim.

* fix(errors): max_turns stays "Exceeded max turns" — observe the repeated failure, don't diagnose it

Reviewer concern on the ABCA-662 work: re-titling a max_turns failure as "Ran out
of turns retrying a failing step" over-claims. The stuck-guard's trailing window is
only the last ~6 tool calls, which genuinely CANNOT distinguish a hard blocker (bad
creds, no permission — more turns won't help) from a long task that made real
progress and hit a recoverable snag only at the tail (more turns / a retry WOULD
help — 662 itself: siblings pushed fine with the same token). Framing the whole run
around its last 6 calls misrepresents the latter.

- error-classifier: drop the separate "retrying a failing step" bucket. A max_turns
  failure stays the plain "Exceeded max turns"; the description/remedy point the
  reader at the observed detail and still surface the environment-blocker path,
  but assert NO cause.
- stuck_guard.recent_failure_summary: emit a NEUTRAL observation ("last tool calls
  repeated: `<cmd>` → <err>") instead of "spinning on failing tool calls". The
  mid-run steer TO the agent (an advisory nudge, not a user surface) still says
  "spinning" — that's fine, it's coaching the agent, not classifying the outcome.
- tests updated to pin the neutral wording + assert the title is NOT re-framed.

* fix+test: guard session-start retry emit, extract + test it, classify raw error

Addresses the aws-samples#599 review (Stack B):

- B1 (MEDIUM): the `session_start_retry` telemetry emit was unguarded — a
  TaskEvents PutItem fault (throttle/timeout, co-occurring with the transient
  session-start failures this path handles) threw AFTER `autoRetried=true` but
  BEFORE the retry ran, so the user was told a second attempt failed when none
  had, and the real retriable cause was discarded. The emit is now best-effort
  (try/catch → WARN-and-continue) so telemetry never aborts/mis-attributes the
  retry. The `correlation` envelope is threaded so the retry event carries the
  same trace context as `session_started` (aws-samples#245).

- B2 (crit-9): the auto-retry had ZERO coverage (it lived inline in the durable
  handler's start-session step the suite never invokes). Extracted to an
  exported `startSessionWithRetry(strategy, input, deps)` — matching the repo's
  "test the exported helper" pattern — and unit-tested all four branches
  (success / non-transient no-retry / transient→retry→success /
  transient→transient→throw) plus the B1 best-effort-emit guard.

- N2: classify the RAW error, not a ``Session start failed: …`` wrapper. The
  wrapper string itself matched a TRANSIENT pattern, so EVERY session-start
  failure classified transient and the "non-transient throws immediately" branch
  was effectively dead (a config/auth fault ate a pointless ~1-min retry).
  Classifying the raw string restores that branch (verified: TaskDefinition-
  inactive → retry; ECS_CLUSTER_ARN-not-configured / AccessDenied → surface).

- N1: soften the `[auto-retried]` comment — it forward-referenced
  renderFailureReply/AUTO_RETRIED_MARKER that don't exist yet. Now states the
  marker is persisted verbatim for a forthcoming failure renderer (retryGuidance
  ships ahead of its consumer); no behaviour claim about rendering today.

Full cdk build green (compile + jest + eslint + synth); 5 new helper tests pass.

* test: cover the max_turns-enrichment wiring seam + window-steer boundary (aws-samples#600 N3/N4)

Follow-up coverage from the aws-samples#600 review (feature approved as-is; tests only):

- N3 (crit-8 wiring seam): the max_turns reason-enrichment was tested only at
  its two pure endpoints (stuck_guard.recent_failure_summary + the classifier on
  a hand-built string) — the append in _resolve_overall_task_status that joins
  them was unverified. Add TestMaxTurnsStuckEnrichment (monkeypatching
  hooks.last_stuck_summary): appends on error_max_turns, does NOT append on a
  non-max_turns error, leaves the reason unchanged when there's no summary, and
  does not double-append when the summary is already present.
- N4 (crit-6 boundary): the window-steer was tested at 6/6 (steers) and 4/6
  (doesn't) but not at the exact WINDOW_FAIL_THRESHOLD `>=` edge. Add
  test_window_steers_at_exactly_the_threshold (5/6 same-fingerprint fails in a
  full window → steers) and test_no_steer_when_window_not_yet_full (5 fails in a
  length-5 history → no steer, since _dominant_window_failure requires a full
  window). Imports WINDOW/WINDOW_FAIL_THRESHOLD so the constants' boundary
  semantics are now pinned.

Full agent suite green (1218); ruff format + check clean.

* fix(cli): mirror errorClass onto ErrorClassification (CDK↔CLI type sync)

aws-samples#599 added `errorClass?: ErrorClassType` to the CDK ErrorClassification, which
serializes into the GET /tasks/{id} `error_classification` response — but the
hand-maintained CLI mirror (cli/src/types.ts) wasn't updated, so the CLI's
structured error display couldn't surface the transient/service/user axis (real
drift per the CLAUDE.md shared-API-shape routing rule).

Add the optional field to the CLI's ErrorClassification, inlined as a union
literal rather than a named `ErrorClassType` export — the types-sync drift check
(scripts/check-types-sync.ts) requires CDK to be the source of truth for any
exported type name, and CDK exports ErrorClassType from error-classifier.ts, not
shared/types.ts. Inlining keeps the field synced without a CLI-only export.

Verified: `//:check:types-sync` OK (57 CLI exports validated), cli build green
(600 tests, compile + eslint clean).

* fix(errors): address aws-samples#599 nits N1-N3 — [auto-retried] breadcrumb + test seams

N1 (Medium): the [auto-retried] marker was never stamped on branch 4 (transient-
then-transient), because startSessionWithRetry THROWS there and the caller's
autoRetried flag is only set on the success paths. A double-transient failure was
told 'reply to retry' instead of 'I already retried' — the exact confusion the
marker exists to prevent. Fix: tag the thrown error with a Symbol (AUTO_RETRIED)
+ export isAutoRetried(); orchestrate-task reads it in the catch and stamps the
marker on both paths a retry ran. Corrected the docstring (was claiming the fact
was 'observable via the thrown-from state' — it wasn't).

N2 (Low): pin the two untested wiring seams. CDK: branch-4 test now asserts
isAutoRetried(err) is true (and false for a first-attempt/non-object failure).
Agent: new tests drive _stuck_guard_between_turns_hook end-to-end and assert the
_LAST_STUCK_SUMMARY latch is written (and cleared on a healthy window) — the
production path the enrichment test's monkeypatch bypasses. Deleting hooks.py's
latch write now fails a test.

N3 (Low): pin retryGuidance's two USER fall-through branches (retryable-user
non-guardrail, not-retryable-user) so the aws-samples#247 failure-renderer copy contract
can't rot.

Full cdk (2345) + agent (1251) gates green.

---------

Co-authored-by: Alain Krok <alkrok@amazon.com>

…osv-scanner (aws-samples#636) (aws-samples#637)

The osv-scanner required check (`Secrets, deps, and workflow scan`) fails on main's
yarn.lock, ejecting every PR from the merge queue (observed on aws-samples#623). Advisories were
published after PR-open scans, so PR-level checks are green while the merge_group
re-scan is red.

- astro 7.0.5 -> 7.1.3 (docs/package.json). Fixes GHSA-4g3v-8h47-v7g6 (XSS),
  GHSA-8mv7-9c27-98vc, GHSA-f48w-9m4c-m7f5. NOTE: intentionally 7.1.3, NOT 7.1.0 —
  7.1.0 (the version Dependabot aws-samples#631/aws-samples#630 target, and the "fixed" version GHSA-4g3v
  cites) is flagged malicious by MAL-2026-10726. 7.1.3 is the current `latest` and is
  past the single poisoned release.
- brace-expansion re-resolved within existing ^1.1.7/^2.0.2 ranges: 1.1.15 -> 1.1.16
  and 2.1.1 -> 2.1.2 (GHSA-3jxr-9vmj-r5cp). Transitive-only; no resolutions pin needed.

Lockfile-only (+ one version string). Verified: `mise run security:deps` exits 0,
`mise //docs:build` builds 68 pages clean, `mise run security:retire` clean.
Supersedes Dependabot aws-samples#631/aws-samples#630 (which bump to the malicious 7.1.0).

Co-authored-by: bgagent <bgagent@noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

…-global (aws-samples#622) (aws-samples#623)

run_task() set the bot's git identity via `git config --global user.name/email`,
which writes to ~/.gitconfig for whatever OS user runs the process. In the
ephemeral ECS container that's intended, but the same code path runs on
developer workstations (local agent runs, dry-runs, pytest reaching run_task),
permanently clobbering the developer's real identity to `bgagent`.

Replace the two `git config --global` subprocess calls with process-scoped
GIT_AUTHOR_NAME/EMAIL and GIT_COMMITTER_NAME/EMAIL env vars, set alongside the
existing os.environ writes. Git honors these for every commit (inherited by
Claude Code and the safety-net commit in post_hooks) without touching any
on-disk config, so container commits stay attributed to bgagent while a
developer's ~/.gitconfig is never modified.

Removes the now-unused `subprocess` import. Adds a regression test asserting
the identity env vars are set. The GitHub PAT flow (GITHUB_TOKEN/GH_TOKEN from
the blueprint's Secrets Manager secret) is unchanged.

Co-authored-by: scottschreckengaust <345885+scottschreckengaust@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

…ext (aws-samples#577) (aws-samples#619)

* feat(jira): include Jira attachments and recent comments in task context (aws-samples#577)

Jira-origin tasks previously saw only the issue summary + description (ADF→
markdown) plus embedded HTTPS image URLs. Jira-hosted `media` file attachments
and issue comments were invisible to the agent, so a ticket that says "see the
attached log" or carries acceptance clarifications in comments would run
under-informed. Bring Jira to parity with Linear's on-demand context reads by
fetching the context authenticated at task-admission time in the webhook
processor (the Atlassian Remote MCP can't run headlessly — see aws-samples#580).

- agent-admission download path (cdk/src/handlers/shared/jira-attachments.ts):
  * downloadScreenAndStoreJiraAttachments — resolve Jira `media` attachments via
    the gateway attachment-content endpoint (api.atlassian.com/ex/jira/{cloudId},
    the only host the 3LO token is valid against), refresh-and-retry-once on
    401/403, enforce the size cap while streaming, validate magic bytes, screen
    through the existing Bedrock Guardrail, upload cleaned bytes to S3, and
    return `passed` AttachmentRecords. Fail-closed: a selected attachment that
    can't be safely fetched/screened throws JiraAttachmentError and the task is
    rejected with a Jira comment. Unsupported/oversized/over-cap attachments are
    silently skipped. Filenames are sanitized and ids validated to a safe token
    so neither can traverse the S3 key / agent on-disk path.
  * fetchRecentHumanComments — recent human (accountType `atlassian`) comments,
    ADF→markdown, oldest-first. Fail-open: any failure proceeds without them.
- create-task-core: TaskCreationContext gains optional `taskId` (so processor-
  uploaded S3 keys match the eventual record) and `preScreenedAttachments`
  (merged verbatim, never re-screened; a non-`passed` record fails closed).
- jira-webhook-processor: wire both in; comments fold under a "## Recent
  comments" heading, bounded so they never push task_description past the 10k
  limit (advisory context must not become a hard gate).
- jira-adf.ts: extract the ADF→markdown walker so the processor and the comment
  helper share it without a circular import (behavior-preserving).
- CDK: pass the attachments bucket to JiraIntegration; grant the processor
  ReadWrite + ATTACHMENTS_BUCKET_NAME env; bump the async processor timeout to
  60s for serial download+screen. No new OAuth scopes (read:jira-work covers it).
- docs: JIRA_SETUP_GUIDE "Issue context: attachments and comments" (supported
  types, limits, skip vs fail-closed reject, comment behavior) + Starlight mirror.

Tests: new jira-attachments.test.ts (download/filter/screen/upload, sanitize,
401 retry, size cap, comment human/app filter + fail-open); processor tests for
comment folding + truncation and fail-closed attachment rejection; create-task-
core tests for preScreenedAttachments merge + taskId. `mise run build` green.

* fix(jira): exempt /v1/jira/webhook from WAF SizeRestrictions_BODY (aws-samples#577)

Jira issue webhook payloads that carry attachment metadata exceed the AWS
managed `SizeRestrictions_BODY` 8 KB limit, so WAF returned 403 at the edge and
the webhook receiver Lambda never ran — the delivery vanished before ABCA saw
it. This is exactly the case aws-samples#577 depends on (an issue with file attachments),
so without this exemption the feature can't work in any WAF-protected deploy.

Mirror the existing `/v1/linear/webhook` and `/v1/github/webhook` handling —
both rules must be updated together:
- AWSManagedRulesCommonRuleSet-TaskPaths (excludes SizeRestrictions_BODY): add
  `/v1/jira/webhook` to the orStatement scope-down so large Jira bodies pass.
- AWSManagedRulesCommonRuleSet (full CRS for other paths): add a NOT
  `/v1/jira/webhook` clause so the path isn't re-covered by the strict rule.

The receiver still HMAC-verifies the raw body and the priority-4 rate-limit
rule still applies, so relaxing the body-size check on this path is safe.

Test: task-api.test.ts asserts the exclusion scope-down contains the Jira path
and the full-CRS scope-down excludes it. 42 pass.

* fix(jira): use Accept: */* when downloading attachment content (aws-samples#577)

The Jira attachment-content endpoint
(`/rest/api/3/attachment/content/{id}`) serves the file's own media type and
responds 406 Not Acceptable to a narrow `Accept: application/octet-stream`.
That made every attachment download fail with HTTP 406, and the fail-closed
path then rejected the whole task ("could not be downloaded (HTTP 406)").
Send `Accept: */*` so the gateway serves the real content type.

Verified against the live endpoint: octet-stream → 406, */* → 200.
Test asserts the download request sets Accept: */*.

* fix(jira): address aws-samples#619 review — orphan cleanup, real-byte cap, comment screening, idempotency (aws-samples#577)

Addresses isadeks's review on PR aws-samples#619:

1. Zero-byte attachment → JiraAttachmentError (fail-closed). A 0-byte body
   passed magic-byte + screening then tripped createAttachmentRecord's size
   guard with a plain Error outside the fail-closed conversion (no ❌ comment).
   Now rejected explicitly with a Jira comment.
2. 50 MB total-attachment cap enforced on REAL downloaded bytes, not the
   attacker-declared `size` metadata (which can under-report). Cumulative real
   bytes tracked in the download loop; throws once over the ceiling.
3. S3 orphan cleanup. downloadScreenAndStoreJiraAttachments now tracks uploaded
   keys and best-effort-deletes them if the batch throws mid-way; the processor
   deletes the returned pre-screened objects when createTaskCore returns non-201
   (and on a 200 idempotent replay, whose objects the replayed task doesn't
   reference). New exported cleanupPreScreenedAttachments helper.
4. Comment content screened SEPARATELY and dropped fail-open. Third-party
   comment text that trips the guardrail no longer fails the reporter's task —
   screenCommentsOrDrop screens the folded comment block and drops it (task
   proceeds) on GUARDRAIL_INTERVENED / screening outage / no guardrail.
5. Deterministic idempotency key (`jira-<issueKey>-<webhookTimestamp>`) so an
   async webhook re-delivery dedupes instead of minting a duplicate task and
   re-downloading every attachment. A 200 idempotent replay is handled as
   success (no ❌ comment), cleaning up the round's re-uploaded objects.
6. Webhook-processor timeout 60s → 300s. 10 serial 10s attachment fetches can
   sum past 60s; a mid-loop kill would orphan objects and force a retry.

Tests: +5 (zero-byte reject, real-byte total cap, mid-batch orphan cleanup,
comment-blocked fail-open drop, deterministic idempotency key + 200-replay).
mise run build green (cdk 2362).

---------

Co-authored-by: Sphia Sadek <isadeks@gmail.com>

… of PRs (aws-samples#620) (aws-samples#621)

* feat(tooling): add /review_prs command to batch-review a filtered set of PRs (aws-samples#620)

Adds .abca/commands/review_prs.md, a thin orchestrator over the existing
single-PR review_pr workflow. It derives a filtered work-list (default:
non-fork PRs requesting your review, unapproved, ready), then fans out one
full review_pr per PR.

The Stage-2 fan-out runs as a Workflow (deterministic multi-agent
orchestration), not prose subagent dispatch: each PR's diff, nested
review_pr agents, and review body stay in a Workflow-spawned subagent's
context, and only a compact schema-validated result per PR (number,
verdict, rationale, review URL) returns to the caller — so a large queue
can't blow the main context. Git pre-staging (worktrees/branches) stays
inline before the Workflow since it mutates shared .git state.

Execution context: /review_prs is an interactive Claude Code / Cursor
command. It cannot run in ABCA's headless runtime, which resolves its SDK
tool surface from an allowlist (runner.py _resolve_allowed_tools /
_FULL_TOOL_SURFACE) that excludes Workflow/Task/Agent — the incident-driven
hardening against a repo-less task spawning a detached Workflow. The
command documents this, notes .claude/ config is discoverable to a
cloned-repo task (so the allowlist, not obscurity, is the guarantee), and
that coding/pr-review-v1 (bound to the pr_review prompt) can't be steered
into it.

Pre-staging is idempotent (forced +pull/<n>/head refspec + run-scoped
scratch dir) and Stage-3 cleanup runs unconditionally (finally-style,
worktrees/branches removed on throw/interrupt too). Stage-1 --json now
fetches headRepositoryOwner so a dropped fork PR can be named.

The command delegates to review_pr.md via a relative link rather than
duplicating the review process, so the review bar stays single-sourced.

Addresses review feedback from theagenticguy on aws-samples#621.

Refs aws-samples#620

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(review_prs): attribute the headless Workflow block to disallowed_tools, not the allow-list (review: isadeks)

isadeks' review (PR aws-samples#621, 4716887845) caught the Execution-context section
crediting the wrong mechanism. Verified against current runner.py on
origin/main:

1. The allow-list is NOT the lock. Under permission_mode="bypassPermissions",
   a tool absent from allowed_tools is auto-ALLOWED, not blocked. The hard
   lock is disallowed_tools=_DISALLOWED_TOOLS (Workflow/Task/Agent/Monitor/
   SendMessage/Cron*), and Cedar PreToolUse default-permits on no-match. The
   doc now attributes the guarantee to disallowed_tools and drops the
   "not in the allowlist" framing.
2. setting_sources is conditional: _resolve_setting_sources returns
   ["project"] only when config.repo_url is set, [] for repo-less tasks.
   Reworded from the unconditional form; the nuance strengthens the point
   (stub reachable only on the repo path, tool off-surface regardless).

Doc-only; drift-prevention + docs build green.

Refs aws-samples#620
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(review_prs): cite the real pr_review system-prompt binding, not loader.py (review)

The Execution-context section credited `agent/src/workflow/loader.py` with
binding the `pr_review` system prompt, but loader.py has no prompt logic — its
`coding/pr-review-v1 → pr_review` entry is the Cedar *principal* (an
audit/identity tag; read-only enforcement keys off `context.read_only` since
aws-samples#248 Phase 2a, per the file's own comment). The real system-prompt binding is
`PR_REVIEW_WORKFLOW` in `agent/src/prompts/pr_review.py`, selected by
`get_system_prompt` in `agent/src/prompts/__init__.py:28`.

The claim's conclusion (no slash-command path into the headless review workflow)
was correct, but the cited file would mislead a maintainer who opened loader.py
to verify it — the same trust-eroding mis-citation class as the earlier
allow-list/deny-list mix-up. Now attributes the prompt to the right files and
notes loader.py's entry is the principal tag.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(review_prs): fix Stage-3 cross-ref and require rationale in result schema (aws-samples#621)

Address two review nits on the /review_prs sketch:

- The agent-prompt parenthetical cited `review_pr` for the submission
  mechanism, but `review_pr.md` tops out at Stage 5 "Present to User" and
  documents no `gh api` path. The POST-to-/reviews mechanism lives in this
  file's own Stage 3 — re-anchor the cross-reference there.
- Add `rationale` to the RESULT schema's `required` list so an agent can no
  longer satisfy the schema with an empty rationale, which the prose
  (L135-136) and the Stage-3 report table both assume is present.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: bgagent <bgagent@noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

… wiring + ECS-parity fixes) (aws-samples#596)

* fix(ecs): write task payload to S3, not inline overrides (aws-samples#502)

The ECS compute strategy inlined the full orchestrator payload (incl. the
large hydrated_context) into the AGENT_PAYLOAD container-override env var.
ECS RunTask caps the TOTAL containerOverrides blob at 8192 bytes, so any real
task was rejected before the container started:

  InvalidParameterException: Container Overrides length must be at most 8192

AgentCore is unaffected — it passes the payload in the InvokeAgentRuntime
request body, which has no comparable limit. The bug only surfaces with a
realistic hydrated payload, which is why the prior ECS smoke test (a small
Rust cargo-check, aws-samples#494) didn't catch it.

Fix — stash the payload out-of-band and pass only a pointer:
- New EcsPayloadBucket construct (mirrors TraceArtifactsBucket): BLOCK_ALL,
  enforceSSL, S3_MANAGED encryption, 1-day lifecycle TTL (payloads are
  ephemeral — read once at boot). Dedicated bucket so the ECS task role's S3
  read is scoped to payloads only and can't touch attachments/traces.
- ecs-strategy: when ECS_PAYLOAD_BUCKET is set, PutObject the payload to
  <task_id>/payload.json and pass AGENT_PAYLOAD_S3_URI in the override; the
  boot command fetches+parses it via boto3. Inline AGENT_PAYLOAD remains as a
  fallback (small payloads / no bucket), so nothing regresses. deleteEcsPayload
  helper removes the object.
- orchestrate-task finalize: best-effort deleteEcsPayload for ECS tasks once
  terminal (the container has long since read it); lifecycle rule is the
  crash backstop.
- EcsAgentCluster: accept payloadBucket, inject ECS_PAYLOAD_BUCKET env, grant
  the task role READ ONLY (untrusted repo code must not write/delete payloads;
  the trusted orchestrator owns write+delete). Session-role-aware.
- task-orchestrator: ecsPayloadBucket prop → grantPut + grantDelete to the
  orchestrator; @aws-sdk/client-s3 added to bundling externals.
- agent.ts: updated the commented uncomment-to-enable ECS scaffolding to wire
  the payload bucket.

Tests: new bucket construct (TTL/SSL/block-public/autoDelete); strategy
S3-write + URI-pointer + inline fallback + deleteEcsPayload (incl. best-effort
swallow + no-op without bucket); cluster read-grant + env var + read-only
(no put/delete). Full build green.

Closes aws-samples#502

* fix: enable corepack in the agent image so yarn/pnpm resolve

Root cause of the exit-127 inert gate: the agent Dockerfile installs node/npm/
mise/uv but NOT yarn, so any repo whose build runs 'yarn install' (incl. ABCA)
hit 'yarn: command not found' and the agent hand-built a ~/bin/yarn shim every
run. corepack (ships with Node 24) installs the yarn/pnpm shims at image-build
time. Systemic — fixes every yarn repo, no per-run shim. Needs redeploy to take
effect.

(cherry picked from commit 2fd5fca)
(cherry picked from commit d5e0e64)

* wire ECS/Fargate substrate (context-gated) at 32GB/8vCPU for heavy builds

AgentCore's fixed microVM envelope OOM-kills CI-parity builds (live-caught
dogfooding ABCA-on-ABCA: the ~2800-test `mise run build` killed the VM at the
build-gate step). AgentCore memory isn't tunable, so route repos that set
`compute_type: 'ecs'` to a Fargate task instead.

- agent.ts: gate EcsAgentCluster + the orchestrator ecsConfig on the
 `compute_type` deploy context (default 'agentcore'). ECS resources only
 synthesize under `--context compute_type=ecs`, so default synth (and the
 bootstrap-coverage test) stays agentcore-only. Mirrors upstream's
 context-gating of the ECS construct.
- ecs-agent-cluster.ts: size the Fargate task at 8 vCPU / 32 GB (was 2/4) —
 a valid ARM64 combo with headroom for the jest worker fleet + tsc that
 AgentCore's envelope can't give. Comment documents the live OOM.
- test: assert the new 8192/32768 sizing.

Verified: default synth has 0 ECS resources; `--context compute_type=ecs`
synth emits AWS::ECS::Cluster + TaskDefinition. Full `mise run build` green.

(cherry picked from commit 8cb7cfa)
(cherry picked from commit 632a36b)

* bump ECS Fargate to 64GB/16vCPU + BUILD_VERIFY_TIMEOUT_S=3600

Live-fired the full `mise run build` on the 32GB ECS task (fork dogfood):
install OK, build ran ~50 min then OOM-killed at the cap (ECS stoppedReason
"OutOfMemoryError: container killed due to memory usage", exit 137; peak
working set ~31.6 GB). Root cause: the monorepo build fans out 4 heavy jobs in
PARALLEL (agent:quality ‖ cdk:build ‖ cli:build ‖ docs:build), each with its
own worker fleet (jest, pytest, esbuild Lambda bundling) — 32 GB had no
headroom for that concurrent peak, and the ~50-min wall-clock also blew the
1800s build-gate cap.

Fix (keep the full build as the gate, give it room):
- ecs-agent-cluster.ts: Fargate 8vCPU/32GB → 16vCPU/64GB (valid ARM64 combo;
 16 vCPU admits 32–120 GB). 2× memory headroom for the parallel storm + more
 cores to shorten wall-clock. Comment records the full sizing history.
- ecs-agent-cluster.ts: inject BUILD_VERIFY_TIMEOUT_S=3600 into the container
 env so a slow-but-healthy CI-parity build isn't mis-flagged as a timeout
 (post_hooks.py reads it; default 1800 stays for AgentCore repos).
- tests: assert 16384/65536 + the new env var.

Verified: default synth ECS-free; --context compute_type=ecs synth emits
Cpu 16384 / Memory 65536 / BUILD_VERIFY_TIMEOUT_S 3600. Full build green.

(cherry picked from commit 11fb3a5)
(cherry picked from commit cd7b8eb)

* fix(ecs): map full payload to run_task so channel/build/cedar fields aren't dropped (ABCA-487)

The ECS boot command hand-listed ~18 run_task kwargs and silently dropped the
rest. On ECS this meant channel_source/channel_metadata never reached run_task,
so resolve_linear_api_token never ran, LINEAR_API_TOKEN was never set, and the
Linear/Jira reaction + channel MCP silently no-op'd — @bgagent tasks on ECS
posted NO 👀 reaction or anything (live-caught: ABCA-487 on the fork, RUNNING
with mcp_servers:[] and no reaction). Also dropped: build_command/lint_command
(build-gate used defaults), cedar_policies + approval_* (HITL guardrails),
base_branch/merge_branches (orchestration stacking), attachments, trace, user_id.
Same "hand-rolled partial payload copy" root as aws-samples#502.

Fix — single source of truth, unit-testable:
- pipeline.run_task_from_payload(p): maps the WHOLE payload dict to run_task's
 signature — rename prompt→task_description / model_id→anthropic_model, filter
 to accepted params (unknown keys ignored, not passed as **kwargs), coerce
 issue_number/pr_number→str + max_turns→int, aws_region falls back to env.
 _RUN_TASK_PARAMS computed once at import (patch-safe).
- entrypoint exports it; ecs-strategy boot command now calls
 run_task_from_payload(p) instead of the hand-listed kwargs.
- tests: 9 agent tests (rename, channel fields ABCA-487, build/cedar/branch,
 coercion, unknown-key drop, None-drop, aws_region, signature guard) +
 ecs-strategy asserts the boot command calls the mapper and no longer hand-lists.

Full build green: agent + cdk 2852 + cli 571 + docs. Deployed to dev
(--context compute_type=ecs; agent image rebuilt).

(cherry picked from commit 777ee0e)
(cherry picked from commit 1639c27)

* fix(ecs): grant task role GetSecretValue on bgagent-{linear,jira}-oauth-* (ABCA-488)

A Linear/Jira-channel task resolves its per-workspace OAuth token from Secrets
Manager (bgagent-linear-oauth-<slug>) at startup to fire the 👀→✅ reaction and
drive the channel MCP. The AgentCore runtime role + orchestrator/fanout/
screenshot/linear-integration roles all have the bgagent-linear-oauth-* prefix
grant, but the ECS task role only had GetSecretValue on the GitHub token. So on
ECS the token fetch hit AccessDenied → LINEAR_API_TOKEN unset → linear_reactions
skipped AND the Linear MCP stayed needs-auth (agent couldn't post comments
either). Live-caught dogfooding on the fork (ABCA-488, ECS task 828dab35).

Fourth ECS-parity gap after aws-samples#502 (payload size) + ABCA-487 (dropped channel
fields): the AgentCore path had a capability the ECS task role didn't.

Fix: grant the ECS task role secretsmanager:GetSecretValue on the
bgagent-linear-oauth-* and bgagent-jira-oauth-* prefixes (GetSecretValue only —
the container reads; the orchestrator owns refresh/PutSecretValue). Nag reason
updated + regression test asserting the prefix grant. Full build green (2853).

(cherry picked from commit 5a886bb)
(cherry picked from commit 49235d4)

* fix(ecs): wire ARTIFACTS_BUCKET_NAME into the Fargate task (ECS-parity, aws-samples#299)

Live-caught: a :decompose on an ecs-configured repo ran on ECS (fix confirmed —
no more 'ECS_CLUSTER_ARN missing') but then FAILED at delivery with
'ValueError: deliver_artifact: ARTIFACTS_BUCKET_NAME is not configured'. The
AgentCore runtime sets ARTIFACTS_BUCKET_NAME; the EcsAgentCluster task def never
got the bucket — an ECS-parity gap (same class as aws-samples#502/ABCA-487). A repo-bound
artifact workflow (coding/decompose-v1) delivers its plan JSON there.

- EcsAgentCluster: new optional artifactsBucket prop → ARTIFACTS_BUCKET_NAME in
 the container env + grantReadWrite on the task role (read+write: the container
 DELIVERS the artifact, unlike the read-only payload bucket). IAM5 suppression
 extended to cover the second scoped S3 grant.
- agent.ts: pass traceArtifactsBucket.bucket (same bucket the runtime uses).
- 3 construct tests (env injected / read+write grant / omitted when absent).

2872 CDK + 571 CLI + 1184 agent green. Held on branch.

(cherry picked from commit 7617d72)
(cherry picked from commit e0dfc93)

* feat(compute): guard compute_type=ecs against a stack without the ECS substrate

A repo onboarded as compute_type=ecs on a stack deployed WITHOUT --context
compute_type=ecs fails every task at session start (no ECS_* env vars). Catch
the config/deploy mismatch early + make the runtime error actionable:

- agent.ts: new ComputeSubstrate CfnOutput — 'ecs' when the gate is on, else
 'agentcore' (ecs is additive; the AgentCore runtime is always present, so an
 agentcore repo works on either).
- cli repo onboard: when --compute-type ecs, read ComputeSubstrate and refuse
 with a redeploy message if it's an explicit non-ecs value. Null (older stacks
 predating the output) is treated as unknown → proceed (runtime backstop).
- ecs-strategy: the missing-env error now names the root cause + remedy
 (redeploy with the gate, or set the repo to agentcore) instead of a bare
 env-var list.
- Tests: CDK output flips with the gate (agentcore default / ecs gated); CLI
 onboard refuses/allows/back-commpat; ecs construct unchanged.

2875 CDK + 575 CLI + 1184 agent green. Held on branch.

(cherry picked from commit cb7c8c6)
(cherry picked from commit 9048db0)

* fix(cdk): raise BUILD task memory 64→120 GB (max Fargate) — ABCA-662 baseline OOM

ABCA-662's pre-agent baseline build was OOM-killed (exit 137) at 64 GB: dogfooding
ABCA-on-ABCA, the full parallel `mise run build` (agent:quality ‖ cdk:build ‖
cli:build ‖ docs:build, each with its own worker fleet) peaked past 64 GB.

Each build task is memory-ISOLATED (its own Fargate microVM), so limiting
concurrency does NOT help a single over-64 GB build — only more per-task RAM or
less build parallelism does. 120 GB is the MAX Fargate admits at 16 vCPU (32–120
in 8 GB steps), so this is the clean experiment: if a build still OOMs here, the
only remaining lever is cutting the build's peak parallelism (serialize the mise
DAG / cap jest --maxWorkers) — there is no more RAM to give.

Pairs with the repo.py fix (an OOM-killed baseline is now infra, not 'already
broken'), so even if a build does hit the ceiling the verdict stays honest.
Tests updated to assert Memory 122880 (both BUILD-def assertions).

(cherry picked from commit 25e2bb1)

* fix(cdk): make ecs-strategy top-of-file import hermetic vs ambient env

The inline-fallback / no-op tests in the top-of-file describe blocks assume the
OPTIONAL vars ECS_PAYLOAD_BUCKET and ECS_PLANNING_TASK_DEFINITION_ARN are ABSENT
when the module is first imported (it reads them as module-level constants). A
dev shell has neither set, so the suite passed locally — but the REAL ECS agent
container HAS ECS_PAYLOAD_BUCKET set (aws-samples#502 payload bucket), so on ECS the const
was truthy and the 'no bucket → inline fallback' + 'no-op' assertions failed:

  FAIL test/handlers/shared/strategies/ecs-strategy.test.ts
    ● startSession › sends RunTaskCommand with correct params ...
    ● deleteEcsPayload without ECS_PAYLOAD_BUCKET › no-ops ...

This was the residual fork baseline-build exit-1: 2 failed / 3093 passed, only
ever reproducible inside the ECS microVM. Surfaced by the live-streaming build
log (the buffered summary had hidden it). Fix: delete both optional vars before
the top-of-file import so it's hermetic regardless of the runner's environment;
the aws-samples#502/aws-samples#299 describe blocks already set them via jest.isolateModules.

(cherry picked from commit 7a2bde9)
(cherry picked from commit 8267c29)

* fix(cdk): grant ec2:DescribeAvailabilityZones to ECS agent task role (cdk synth on fresh clone)

A CDK-based target repo's build gate runs `cdk synth`. When the stack is wired
to a concrete env ({account, region}), CDK does a synth-time availability-zone
context lookup (ec2:DescribeAvailabilityZones). A developer box caches the result
in the gitignored cdk.context.json so synth is hermetic; the agent clones fresh,
so there is no cache and the live lookup fires. The ECS task role lacked the
action, so synth failed with:

  ERROR ...EcsAgentClusterTaskRole... is not authorized to perform:
        ec2:DescribeAvailabilityZones ...
  Synthesis finished with errors

→ a FALSE build-gate failure on code that builds fine everywhere else. Same
ECS-parity class as ABCA-488 (GetSecretValue) and F-2 (CreateEvent): a permission
the AgentCore path had but the ECS task role didn't.

Live-caught on the ABCA fork: baseline `mise run build` passed all 3095 tests
then died at `cdk synth -q`, surfaced only by the live-streaming build log.
Grant is a read-only describe (Resource:* — EC2 describe actions have no
resource-level scoping; IAM5 suppressed, no mutation/data access). +1 regression
test pins the statement.

(cherry picked from commit 3fc9060)
(cherry picked from commit 2bf12f4)

* fix(ecs): grant ECS task role AgentCore Memory access (F-2, ABCA-488-class)

Live-caught during the fork stress smoke (ABCA-495): the ECS TaskDefTaskRole
got AccessDeniedException on bedrock-agentcore:CreateEvent for the AgentMemory
resource, so the agent's cross-task learning writes (write_task_episode /
write_repo_learnings) silently no-op'd (WARN) on EVERY ECS task — memory never
persisted on the fork's ECS-only substrate.

Same class as ABCA-488: the AgentCore runtime role gets memory access via
agentMemory.grantReadWrite(runtime) in agent.ts, and the orchestrator gets it
too, but the ECS task role never did.

Fix: EcsAgentCluster gains an optional agentMemory prop; when provided the task
role gets agentMemory.grantReadWrite (read actions + CreateEvent), scoped to the
memory ARN (synth-verified: no wildcard resource, so the existing IAM5 nag
suppression is unaffected). agent.ts passes agentMemory to the ECS cluster
alongside the existing memoryId. Omitted in isolated construct tests /
memory-less deploys → no grant (asserted).

Tests: construct asserts CreateEvent on the task role scoped to MemoryArn when
wired, and NO bedrock-agentcore grant when unwired. Full cdk build green (2883).

(cherry picked from commit c23d49fbead30ed52860e3975815e3643b22ade0)
(cherry picked from commit 44bb71e)

* docs(bootstrap): correct the ECS ComputeTypes enable instructions

The //cdk:bootstrap task hint and DEPLOYMENT_ROLES.md both said to enable the ECS
compute backend with 'mise //cdk:bootstrap -- --context ComputeTypes=agentcore,ecs'.
That does NOT work: ComputeTypes is a CloudFormation *template parameter*, and this
CDK version's 'cdk bootstrap' has no way to set one — there's no --parameters flag,
and --context sets CDK construct context, not a CFN parameter. So the ECS policy
(IaCRole-ABCA-Compute-ECS, conditional on ComputeTypes containing 'ecs') was never
attached, and a --context compute_type=ecs deploy then failed with AccessDenied on
ecs:* — live-caught deploying the substrate to dev.

Correct it to the mechanism that actually works: bootstrap normally, then set the
parameter directly on the CDKToolkit stack via
'aws cloudformation update-stack ... ParameterKey=ComputeTypes,ParameterValue=agentcore,ecs'
(with a describe-stacks verify). Fixed in the mise task description + comment and
both DEPLOYMENT_ROLES.md occurrences; Starlight mirror regenerated. Drift gate green.

(cherry picked from commit a46683e)

* fix(ecs): remove dead ECS_PAYLOAD_OBJECT_KEY_PREFIX export (review B1)

The `export const ECS_PAYLOAD_OBJECT_KEY_PREFIX = ''` constant was referenced
nowhere — ecsPayloadKey() (ecs-strategy.ts) builds `<task_id>/payload.json`
independently and already documents that layout in its own docstring. The dead
export was a "prefix" whose value was '' with a docstring describing a key
layout it didn't produce, and it raised the knip dead-code count, tripping the
ratchet inside `mise run build`. Delete it; ecsPayloadKey remains the single
source of truth for the key layout.

* docs+feat: address review nits N1–N4 on the ECS substrate

Review follow-ups for aws-samples#596 (fix itself unchanged; B1 dead-export fixed in the
base PR aws-samples#503):

- N1: correct the stale "64 GB / 16 vCPU" comment in agent.ts — the task is
  larger (64 GB was itself OOM-killed per the construct's sizing history).
  Defer the exact figure to EcsAgentCluster rather than duplicate/drift it.
- N2: reword the memory-grant + oauth-grant comments — an AccessDenied on those
  paths is LOGGED (memory.py treats it as an infra failure; config.py's token
  resolver logs it), not "silently" no-op'd. Describe the user-visible effect
  (no persisted learning / no 👀→✅ reaction) rather than pin a log level that
  drifts.
- N3: the ec2:DescribeAvailabilityZones comment already frames it correctly as a
  FALSE build-gate failure (not a WARN no-op) — no change needed; noted here for
  completeness.
- N4: run_task_from_payload now emits a WARN when it drops a KNOWN orchestrator
  key (build_command / merge_branches / base_branch / github_token_secret_arn)
  that run_task doesn't accept — expected today (consumed elsewhere / not yet
  wired), but makes a future "wired one side, forgot the other" no-op visible
  instead of silent (the ABCA-487 class). Foreign keys still drop quietly.
  + 2 tests (warns on a known dropped key; stays quiet on a foreign key).

Full cdk build green (2286) + full agent suite green (1194); eslint/ruff clean.

* style: ruff-format the N4 payload-key block (fix build-mutation failure)

CI's "Fail build on mutation" tripped: I ran `ruff check` (passed) but not
`ruff format`, so the `_KNOWN_ORCHESTRATOR_KEYS = frozenset({...})` set literal
and the two-line `log(...)` call weren't in ruff's canonical multi-line form.
`ruff format` normalizes them; no behavior change (12 payload tests still pass).

* fix+docs: WARN on dropped task_started_at (HITL parity) + defensive max_turns + comment nits

Follow-up on the aws-samples#596 re-review (code was already approved-quality; these are the
new non-blocking finding + 3 nits):

- task_started_at HITL parity: AgentCore's server.py exports task_started_at as
  TASK_STARTED_AT, which hooks._remaining_maxlifetime_s() uses to clip the Cedar
  HITL approval-gate maxLifetime. The ECS boot path bypasses server.py and never
  sets it, so run_task_from_payload dropped it SILENTLY — a fail-open AgentCore↔ECS
  HITL divergence. Added task_started_at to _KNOWN_ORCHESTRATOR_KEYS so the drop
  now WARNs (surfaces the gap). Fully wiring TASK_STARTED_AT into the ECS
  containerEnv is a tracked follow-up; this makes the divergence visible today.
- max_turns defensive coercion: a malformed max_turns raised ValueError mid-boot
  while every other field defaults defensively. Now drops it (run_task default
  applies) with a WARN, matching the surrounding style.
- Nit: artifactsBucket JSDoc no longer claims this bucket is the `--trace` upload
  target (it wires ARTIFACTS_BUCKET_NAME only; the trace uploader reads
  TRACE_ARTIFACTS_BUCKET_NAME, unset here — noted as a separate ECS-parity gap).
- Nit: dropped `2>/dev/null` from the Dockerfile corepack prepare so the
  prepare-failed diagnostic isn't hidden (the `|| corepack enable` fallback
  still guarantees resolvable shims — no regression to the exit-127 inert gate).

Tests: +3 (task_started_at WARN, malformed-max_turns dropped-not-raised, valid
max_turns still coerced). Full agent suite green (1195); cdk tsc + construct
tests green; ruff format + eslint clean.

* fix(ecs): address aws-samples#596 review — drop over-privileged artifacts grant + nits

B1 (least-privilege regression): remove props.artifactsBucket.grantReadWrite
from the ECS task role. coding/decompose-v1 delivers its plan via the assumed
SessionRole (deliverers.py -> tenant_client), scoped to artifacts/${task_id}/*,
exactly like the AgentCore runtime (whose task role likewise has NO direct
artifacts grant). The whole-bucket grant over-privileged the untrusted-code
role and broke cross-task isolation (a task could read/clobber other tasks'
artifacts/<other_id>/, traces/, attachments/). Task role keeps only the
ARTIFACTS_BUCKET_NAME env. Correct the inverted 'parity' comment and drop the
now-stale artifacts clause from the cdk-nag IAM5 reason.

Test: flip 'grants READ+WRITE on artifacts' → asserts the task role has NO S3
Put/Delete action at all (the read-only aws-samples#502 payload GetObject*/List* grant is
not flagged).

N4: add lint_command to _KNOWN_ORCHESTRATOR_KEYS (sibling of build_command) so a
future 'wired build_command, forgot lint_command' contract gap WARNs instead of
dropping silently.

(N1/N2/N3 comment nits were already addressed on the branch head; B1 dead-const
ECS_PAYLOAD_OBJECT_KEY_PREFIX no longer present. B2 governance handled separately.)

* fix(ecs): address aws-samples#596 re-review nits — stale parity comments + WARN noise + max_turns coercion

Scott's fresh re-review (head 86ab249) is Approve-with-nits: B1 (over-privilege)
and B2 (governance) resolved; remaining asks are doc-accuracy + WARN-channel
hygiene.

- N1: rewrite the artifactsBucket JSDoc (ecs-agent-cluster.ts) that still claimed
  a read/write task-role grant the B1 fix deliberately removed — now states
  env-only wiring with delivery through the task_id-scoped SessionRole (parity
  with the AgentCore runtime role, which has no artifacts grant). The grant block
  ~30 lines below was already corrected in the B1 commit; this was its residual
  half.
- N2: same inverted-comment fix at the agent.ts wiring site — '(read+write grant
  in the construct)' → env-only + SessionRole delivery.
- N3: drop github_token_secret_arn from _KNOWN_ORCHESTRATOR_KEYS. It is ALWAYS
  present and ALWAYS resolved via the GITHUB_TOKEN_SECRET_ARN env, so listing it
  fired the known-key WARN on 100% of ECS boots — pure noise diluting the channel
  meant for genuine future contract gaps. Now falls through as a quiet foreign-key
  drop; comment records why it must not be re-added. +test asserting no WARN.
- N4: max_turns int() coercion accepted a bool (int(True)==1) and truncated a
  non-integral float (int(3.9)==3), and the comment falsely claimed it 'matches
  how every other field is handled' (it is the one non-str coercion). Now rejects
  bools + non-integral floats with a breadcrumb; valid int / int-string / int-float
  still pass. +test. Reachable only via a corrupt payload (orchestrator emits a
  real int), so cosmetic — bundled since cheap.
- N5: no-op — the Dockerfile corepack line already has no 2>/dev/null.

Gates: cdk 2355 tests + eslint + synth green; agent 1268 tests + ruff + ty green.
Non-blocking aws-samples#608 test-seam gaps (finalize deleteEcsPayload, boot-uri parse,
entrypoint re-export, zero-ECS-synth assert) remain tracked, not in scope here.

---------

Co-authored-by: bgagent <bgagent@noreply.github.com>
Co-authored-by: Alain Krok <alkrok@amazon.com>

# Conflicts:
#	agent/Dockerfile
#	agent/src/hooks.py
#	agent/src/pipeline.py
#	agent/tests/test_hooks.py
#	agent/tests/test_run_task_from_payload.py
#	agent/tests/test_stuck_guard.py
#	cdk/src/constructs/ecs-agent-cluster.ts
#	cdk/src/handlers/orchestrate-task.ts
#	cdk/src/handlers/shared/error-classifier.ts
#	cdk/src/stacks/agent.ts
#	cdk/test/constructs/ecs-agent-cluster.test.ts
#	cdk/test/handlers/shared/error-classifier.test.ts
#	cdk/test/stacks/agent.test.ts

…scanner (aws-samples#638)

osv-scanner (required 'Secrets, deps, and workflow scan') fails on main's
yarn.lock, ejecting every PR from the merge queue via the merge_group re-scan
(observed on aws-samples#612, aws-samples#616). Newly-published advisories on pre-existing deps — same
class as aws-samples#636 (astro/brace-expansion), different packages:

  GHSA-2p49-hgcm-8545  svgo             4.0.1  -> 4.0.2   (CVSS 8.2)
  GHSA-8r6m-32jq-jx6q  fast-xml-parser  5.9.3  -> 5.10.1  (CVSS 8.7)
  GHSA-v2hh-gcrm-f6hx  fast-uri         3.1.3  -> 3.1.4   (CVSS 7.5)

All three re-resolve WITHIN their existing ranges (svgo/fast-uri transitive;
fast-xml-parser is ^5.7.0 direct, 5.10.1 is in-range), so this is yarn.lock-only
— no package.json / version-string / source change. All fix versions clean in OSV.

Verified: mise run security:deps -> 'No issues found' (exit 0);
yarn install --frozen-lockfile consistent; mise //docs:build green (68 pages).

Closes aws-samples#638.

Post-merge coherence fixes the conflict-marker resolution alone didn't catch
(only the full build/test gate did):

- hooks.py: post_tool_use_hook had a DUPLICATE stuck_guard kwarg + a duplicated
  K7 docstring/record_tool_result block (both sides added stuck_guard to the same
  signature; git kept both → SyntaxError 'duplicate argument', and the guard was
  fed twice per tool call). Collapsed to one stuck_guard param + one record block.
- pipeline.py: restored 'import subprocess' (main's aws-samples#623 dropped it when it removed
  the git-config subprocess calls, but lv's A6 code_changed block still calls
  subprocess.run → would NameError at runtime). Also the linter's import-order fix.
- test_pipeline.py: main's test_git_identity_uses_env_vars_not_global_config mocked
  verify_build/verify_lint with a bare bool, but the resolved source keeps lv's
  VerifyOutcome shape (build_outcome.passed) → AttributeError. Fixed both mocks to
  VerifyOutcome(passed=True), matching every other lv pipeline test.

Gates green after: cdk 3207 tests + synth + eslint; agent 1374 tests + ruff + ty
(under AGENT_SESSION_ROLE_ARN set — no ECS hang).

Task-Id: 01KY3SE6KPQW8DP1QGCVBZMPWZ
Prompt-Version: 1c9c10e027a2

…gration branch

Combines the completed sub-issue branch (task 01KY3SE6KPQW8DP1QGCVBZMPWZ,
abca-736 'merge-verify-ecs') which carries the linear-vercel integration
(ECS Fargate compute backend + lv↔main conflict resolution) plus the
docs/merge-check/ecs.md post-merge marker, into this epic's single
reviewable integration branch.

Integration/merge only — no new features.
Task-Id: 01KY5YH2PKY0SDHGBM6DVG39YB
Prompt-Version: 1c9c10e027a2